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.

# 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](/docs/premium-apis/device-location/api-endpoints/usage-trigger-management/createnewtrigger) ## 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](https://thingspace.verizon.com/documentation/api-documentation.html#/http/session-management/guides/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. ```json { "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 ```json { "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: ```json { "errorCode": "The 3-digit HTML error code", "errorMessage": "string" } ``` Error codes and messages are listed on the [Error Codes page](https://thingspace.verizon.com/documentation/api-documentation.html#/http/device-location/error-codes), along with explanations and suggestions for corrective actions.

Verizon 5G Edge API Portal

Create Usage Trigger