Create Usage Trigger
POST /usage/triggers
Create a new usage trigger, which will send an alert when the number of device location service transactions reaches a specified percentage of the monthly subscription amount, such as 90% or 100%. You can create as many usage triggers in an account as needed.
Uses and Requirements
Note: This method uses the /subsc/v1 basepath, not /loc/v1 used by other Device Location API requests.
ThingSpace checks the number of transactions used by an account once per day. It is possible for an account to exceed 100% of the monthly subscription amount before the daily usage check, and thus incur overage charges.
If you have registered for Location callback messages, ThingSpace will automatically send callback alerts when any trigger condition is met. For example, if you create a trigger to send an SMS alert when usage reaches 90%, ThingSpace will send the SMS alert and a callback alert.
HTTP Request
POST https://thingspace.verizon.com/api/subsc/v1/usage/triggers
Resource Path and Query Parameters
None.
Header Parameters
The request header must contain a current ThingSpace authorization token and a current VZ-M2M session token. For more details on how to get these tokens, visit Getting Started.
| Parameter Name | Data Type | Description |
|---|---|---|
| Authorization (required) | string | HTTP Authorization bearer token: Authorization: Bearer {token}. |
| VZ-M2M-Token (required) | string | A valid session token returned by POST /api/m2m/v1/session/login using the primary account’s credentials. |
| Content-Type (required) | string | Must be application/json: Content-Type: application/json. |
Request Body
The request body contains the account name and the definition of the new trigger. To create a trigger that only sends callback alerts, set both sendSmsNotification and sendEmailNotification to false.
| Parameter Name | Data Type | Description |
|---|---|---|
| accountName (required) | string | The Verizon billing account that the trigger belongs to. You cannot move a trigger to a different account. |
| serviceName (required) | string | Must be “location” for device location service. |
| triggerName (required) | string | A name of the trigger. |
| thresholdValue (required) | string | The percent of subscribed usage required to activate the trigger, such as 90 or 100. |
| allowExcess (required) | Boolean | (Not currently functional) For triggers with thresholdValue = 100, set allowExcess to true to allow additional device location service requests after the thresholdValue is reached. Additional requests may result in overage charges. Set to false to block further use of the service until the next billing period. Default is false. |
| sendSmsNotification (required) | Boolean | Set to true to send SMS (text) messages when the thresholdValue is reached. |
| smsPhoneNumbers (required) | string | A comma-separated list of phone numbers to send SMS alerts to. Digits only; no dashes or parentheses, etc. |
| sendEmailNotification (required) | Boolean | Set to true to send email messages when the thresholdValue is reached. |
| emailAddresses (required) | string | A comma-separated list of email address to send email alerts to. |
Example Request Body
Create a usage trigger to send an SMS message when the number of device location service transactions reaches 90% of the subscribed amount.
{
"accountName": "0000123456-00001",
"serviceName": "location",
"triggerName": "90 percent",
"thresholdValue": "90",
"allowExcess": true,
"sendSmsNotification": true,
"smsPhoneNumbers": "8881236543, 8881234321"
}Success Responses
Status 200
A success response contains the complete settings of the trigger resource.
Example Success Response
{
"triggerId": "595f5c44-eeee-ffff-gggg-020a1545a84d",
"triggerName": "90 percent",
"accountName": "0000123456-00001",
"serviceName": "location",
"thresholdValue": "90",
"allowExcess": true,
"sendSmsNotification": true,
"smsPhoneNumbers": "10-digit phone number",
"sendEmailNotification": false,
"emailAddresses": "",
"createDate": "2018-08-11",
"updateDate": "2018-08-12"
}Failure Responses
All error messages are returned in this format:
{
"errorCode": "The 3-digit HTML error code",
"errorMessage": "string"
}Error codes and messages are listed on the Error Codes page, along with explanations and suggestions for corrective actions.