POST /usage/triggersCreate 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.
See also:
Update a Usage Trigger
Get Usage Triggers
Delete a Usage Trigger
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.
POST https://thingspace.verizon.com/api/subsc/v1/usage/triggers
None.
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 /api/m2m/v1/session/login using the primary account’s UWS credentials. |
| Content-Type required |
string | Must be application/json. |
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 optional |
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 optional |
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 optional |
Boolean | Set to true to send SMS (text) messages when the thresholdValue is reached. |
| smsPhoneNumbers optional |
string | A comma-separated list of phone numbers to send SMS alerts to. Digits only; no dashes or parentheses, etc. |
| sendEmailNotification optional |
Boolean | Set to true to send email messages when the thresholdValue is reached. |
| emailAddresses optional |
string | A comma-separated list of email address to send email alerts to. |
Create a usage trigger to send an SMS message when the number of device location service transactions reaches 90% of the subscribed amount.
{
"accountName": "1000012345-00001",
"serviceName": "location",
"triggerName": "90 percent",
"thresholdValue": "90",
"allowExcess": true,
"sendSmsNotification": true,
"smsPhoneNumbers": "8881236543, 8883214321"
}
Status 200
A success response contains the complete settings of the trigger resource.
{
"triggerId": "595f5c44-c31c-4552-8670-020a1545a84d",
"triggerName": "90 percent",
"accountName": "1000012345-00001",
"serviceName": "location",
"thresholdValue": "90",
"allowExcess": true,
"sendSmsNotification": true,
"smsPhoneNumbers": "5558794321",
"sendEmailNotification": false,
"emailAddresses": "",
"createDate": "2018-08-11",
"updateDate": "2018-08-12"
}
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.