Create Usage Trigger

Create a 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.

Contents

See also:
Update a Usage Trigger
Get Usage Triggers
Delete a Usage Trigger

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.

Request Components

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 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.

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
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.

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": "1000012345-00001",
  "serviceName": "location",
  "triggerName": "90 percent",
  "thresholdValue": "90",
  "allowExcess": true,
  "sendSmsNotification": true,
  "smsPhoneNumbers": "8881236543, 8883214321"
}

Success Responses

Status 200

A success response contains the complete settings of the trigger resource.

Example Success Response

{
  "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"
}

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!