Create a Trigger for Service Impacting Events
POST /v2/triggers
This API allows an application to register for callback notifications during a relevant network outage. It is recommended to also subscribe to the Reachability API service to receive subsequent callbacks when devices come back online after a Service Impacting Event.
Creating a trigger for Service Impacting Events Is similar to creating any trigger in Connectivity Management. The only difference is a few additional values for Service Impacting Events. This page will cover the values Service Impacting Events and provide examples of what requests look like with the new values. The API Reference page for creating a trigger can be found at Create a Trigger for Usage Notifications.
HTTP Request
POST https://thingspace.verizon.com/api/m2m/v2/triggers
Header Parameters
The request header must set the content-type to JSON, 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: VZ-M2M-Token: {M2Mtoken} |
| Content-Type required | string | Must be application/json: Content-Type: application/json |
Request Parameters
All parameters are required unless marked "optional".
| Parameter | Data Type | Description |
|---|---|---|
| triggerName | string | The name of the trigger as defined by the user. |
| triggerCategory | string | The type of trigger being created. For these triggers, the type will always be ServiceImpactingEvents |
| serviceImpactingEventsTrigger | object | Filtering details for what the trigger will apply to. |
| filterCriteria | object | Contains the filter details. |
| accountName | string | The numeric name of the account. This must include all leading zeros. |
| deviceGroupName | string | The user-assigned name of the group. |
| notification | object | Contains details about the notification |
| notificationType | string | The type of notification must be “PerEvent” for ServiceImpactingEvents. |
| callback | boolean | Will be set to "true" if callbacks are requested to be enabled for this trigger. |
| severity | string | Desired severity for notifications. Valid values include:
|
| active | boolean | The status of the trigger. If the trigger is active, this will show "true". If the trigger is not active, this will show "false". |
Request Body
Example request:
{
"triggerName": "user-defined trigger name",
"triggerCategory": "ServiceImpactingEvents",
"serviceImpactingEventsTrigger": {
"filterCriteria": {
"accountName": "0000123456-00001",
"deviceGroupName": "user-defined group name"
}
},
"notification": {
"notificationType": "PerEvent",
"callback": true,
"severity": "Minor"
},
"active": true
}
Success Responses
Status 200
Example Success Response
{
"requestId": "d1f08526-5443-4054-9a29-4456490ea9f8"
}Callback Response
These endpoints send responses asynchronously. In order to read the results a callback is required. To learn more about callbacks, please visit About Callback Services.
Example callback response:
{
"username": "user's login (used for callback registration)",
"password": "user's password",
"requestId": "d1f08526-5443-4054-9a29-4456490ea9f8",
"deviceResponse": {
"alertServiceResponse": {
"triggerId": "system generated trigger identifier",
"triggerName": "user-defined trigger name",
"triggerDateTime": "6/9/2023 10:23:47 PM",
"message": "Service Impacting Event Alert for Account Number 0000123456-00001 on 06/09/2023 ",
"notificationType": "Per Event",
"accountName": "0000123456-00001",
"serviceImpactingEvents": {
"deviceIds": [
{
"id": "10-digit phone number",
"kind": "MDN"
},
{
"id": "10-digit phone number",
"kind": "MDN"
}
],
"date": "2022-08-02T11:40:04",
"reason": "OUTAGE",
"service": "service name or identifier",
"city": "Irving",
"state": "TX"
}
}
},
"callbackCount": 1,
"maxCallbackThreshold": 4
}
Callback Parameters
| Parameter | Data Type | Description |
|---|---|---|
| username | string | The user's login information. |
| password | object | The user's password. |
| requestId | string | The requestId being viewed. This is a system generated value from the request above. |
| deviceResponse | object | Contains the response details from the device(s). |
| alertServiceResponse | object | Contains the details of the alert causing the trigger to respond. |
| triggerId | string | System generated ID. |
| triggerName | string | The user-defined name of the trigger. |
| triggerDateTime | string | The timestamp of when the trigger responded. |
| message | string | A system generated message. |
| notificationType | string | The type of notification must be “PerEvent” for ServiceImpactingEvents. |
| accountName | string | The numeric name of the account, including leading zeros. |
| serviceImpactingEvents | object | Details about the service impact causing the alert. |
| deviceIds | array | A list of devices impacted. |
| id | string | The value of the identifier |
| kind | string | The type of identifier. |
| date | string | The timestamp of the network event. |
| reason | string | The description of the specific service impacting event |
| service | string | The name of the service impacted by the event. |
| city | string | The name of the city where the event occurred. |
| state | string | The 2 letter state code. This conforms to ISO-3166. |
| callbackCount | string | The number of responses for deviceResponse found. |
| maxCallbackThreshold | string | The maximum number of responses for deviceResponse allowed. |
Failure Responses
Status 400
All error messages are returned in this format:
{
"errorCode": "The 3-digit HTML error code",
"errorMessage": "string"
}