Create alert configurations.

Creates an alert configuration.

Rate limit: 100 requests/min (learn more about rate limits here).

To use this endpoint, select Write Alerts under the Alerts category when creating or editing an API token. Learn More.

Submit Feedback: Likes, dislikes, and API feature requests should be filed as feedback in our API feedback form. If you encountered an issue or noticed inaccuracies in the API documentation, please submit a case to our support team.

POST /alerts/configurations

Create alert configurations.

cURL

curl --request POST \
  --url https://api.samsara.com/alerts/configurations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "actions": [
    {
      "actionTypeId": 1,
      "actionParams": {
        "driverAppNotification": {},
        "recipients": [
          {
            "type": "user",
            "contactId": "1234",
            "notificationTypes": [
              "sms",
              "sms",
              "push",
              "push"
            ],
            "roleId": "67004a16-be3c-4ef6-a51b-1c45a2c27a92",
            "userId": "1234"
          }
        ]
      }
    }
  ],
  "isEnabled": true,
  "name": "My Harsh Event Alert",
  "scope": {
    "all": false,
    "assets": [
      {
        "assetId": "12443",
        "assetType": "trailer"
      }
    ],
    "drivers": [
      {
        "driverId": "12434"
      }
    ],
    "tags": [
      {
        "id": "3914",
        "name": "East Coast",
        "parentTagId": "4815"
      }
    ],
    "widgets": [
      {
        "widgetId": "12434"
      }
    ]
  },
  "triggers": [
    {
      "triggerTypeId": 1000,
      "triggerParams": {
        "dvirSubmittedDevice": {
          "dvirMinDurationMilliseconds": 600000,
          "dvirSubmissionTypes": [
            "SAFE_NO_DEFECTS",
            "SAFE_WITH_DEFECTS"
          ]
        },
        "vehicleFaultCode": {
          "hasAnyAmberWarningLampCodes": true,
          "hasAnyFaultCodes": true,
          "hasAnyMalfunctionIndicatorLampCodes": true,
          "hasAnyProtectionLampCodes": true,
          "hasAnyRedStopLampCodes": true,
          "hasAnyTrailerAbsLampCodes": true,
          "minDurationMilliseconds": 600000,
          "specificFaultCodes": [
            {
              "faultCode": "1067",
              "type": "J1939_SPN"
            }
          ]
        }
      }
    }
  ],
  "externalIds": {}
}
'

200

{
  "data": {
    "actions": [
      {
        "actionTypeId": 1,
        "actionParams": {
          "driverAppNotification": {
            "inAppNotificationOptions": {
              "isEnabled": true,
              "canDictateAlertTitle": false,
              "canPlayAlertSound": false,
              "customText": "Custom text"
            },
            "pushNotificationOptions": {
              "isEnabled": true
            }
          },
          "recipients": [
            {
              "type": "user",
              "contactId": "1234",
              "notificationTypes": [
                "sms",
                "sms",
                "sms"
              ],
              "roleId": "67004a16-be3c-4ef6-a51b-1c45a2c27a92",
              "userId": "1234"
            }
          ],
          "webhooks": {
            "webhookIds": [
              "123",
              "123",
              "123",
              "123"
            ],
            "payloadType": "enriched"
          }
        }
      }
    ],
    "createdAtTime": "2019-06-13T19:08:25Z",
    "id": "e1c5dffc-c7b7-47b0-a778-6a65de638abf",
    "isEnabled": true,
    "lastModifiedAtTime": "2019-06-13T19:08:25Z",
    "name": "My Harsh Event Alert",
    "scope": {
      "all": true,
      "assets": [
        {
          "assetId": "12443",
          "assetType": "trailer"
        }
      ],
      "drivers": [
        {
          "driverId": "12434"
        }
      ],
      "tags": [
        {
          "id": "3914",
          "name": "East Coast",
          "parentTagId": "4815"
        }
      ],
      "widgets": [
        {
          "widgetId": "12434"
        }
      ]
    },
    "triggers": [
      {
        "triggerTypeId": 1000,
        "triggerParams": {
          "ambientTemperature": {
            "minDurationMilliseconds": 600000,
            "operation": "GREATER",
            "temperatureCelcius": 60,
            "cargoIsFull": true,
            "doorsAreClosed": true
          },
          "cellSignalLoss": {
            "minDurationMilliseconds": 600000
          },
          "defLevel": {
            "defLevelPercent": 100,
            "minDurationMilliseconds": 600000,
            "operation": "GREATER"
          },
          "deviceMovement": {
            "minDurationMilliseconds": 600000
          },
          "documentSubmitted": {
            "templateIds": [
              "23b78345-d098-3k4j-1pk3-4k5j6938j289",
              "23b78345-d098-3k4j-1pk3-4k5j6938j289",
              "23b78345-d098-3k4j-1pk3-4k5j6938j289"
            ]
          },
          "dvirSubmittedDevice": {
            "dvirMinDurationMilliseconds": 600000,
            "dvirSubmissionTypes": [
              "UNSAFE",
              "SAFE_NO_DEFECTS"
            ]
          },
          "engineIdle": {
            "minDurationMilliseconds": 600000
          },
          "engineOff": {
            "minDurationMilliseconds": 600000
          },
          "engineOn": {
            "minDurationMilliseconds": 600000
          },
          "fuelLevel": {
            "fuelLevelPercent": 20,
            "minDurationMilliseconds": 600000,
            "operation": "LESS"
          },
          "gatewayDisconnected": {
            "minDurationMilliseconds": 3600000
          },
          "gatewayUnplugged": {
            "minDurationMilliseconds": 600000
          },
          "geofenceEntry": {
            "location": {
              "addressIds": [
                "Placeat est voluptatem id tenetur amet.",
                "Omnis consectetur quis neque nihil molestiae harum."
              ],
              "addressTypes": [
                "agricultureSource",
                "unauthorizedZone",
                "undefined"
              ],
              "circle": {
                "name": "My Geofence Cirlce",
                "radiusMeters": 23,
                "latitude": 37.7749,
                "longitude": 137.7749
              },
              "polygon": {
                "name": "My Geofence Polygon",
                "vertices": [
                  {
                    "latitude": 37.7749,
                    "longitude": 137.7749
                  }
                ]
              },
              "tagIds": [
                "4815",
                "4815",
                "4815",
                "4815"
              ]
            }
          },
          "geofenceExit": {
            "location": {
              "addressIds": [
                "Placeat est voluptatem id tenetur amet.",
                "Omnis consectetur quis neque nihil molestiae harum."
              ],
              "addressTypes": [
                "agricultureSource",
                "unauthorizedZone",
                "undefined"
              ],
              "circle": {
                "name": "My Geofence Cirlce",
                "radiusMeters": 23,
                "latitude": 37.7749,
                "longitude": 137.7749
              },
              "polygon": {
                "name": "My Geofence Polygon",
                "vertices": [
                  {
                    "latitude": 37.7749,
                    "longitude": 137.7749
                  }
                ]
              },
              "tagIds": [
                "4815",
                "4815",
                "4815",
                "4815"
              ]
            }
          },
          "gpsSignalLoss": {
            "minDurationMilliseconds": 600000
          },
          "harshEvent": {
            "types": [
              "haFalsePositive",
              "haRedLightViolation",
              "haDistractedDriving",
              "haDistractedDriving"
            ]
          },
          "hosViolation": {
            "maxUntilViolationMilliseconds": 600000,
            "violation": "CaliforniaMealbreakMissed"
          },
          "insideGeofence": {
            "location": {
              "addressIds": [
                "Placeat est voluptatem id tenetur amet.",
                "Omnis consectetur quis neque nihil molestiae harum."
              ],
              "addressTypes": [
                "agricultureSource",
                "unauthorizedZone",
                "undefined"
              ],
              "circle": {
                "name": "My Geofence Cirlce",
                "radiusMeters": 23,
                "latitude": 37.7749,
                "longitude": 137.7749
              },
              "polygon": {
                "name": "My Geofence Polygon",
                "vertices": [
                  {
                    "latitude": 37.7749,
                    "longitude": 137.7749
                  }
                ]
              },
              "tagIds": [
                "4815",
                "4815",
                "4815",
                "4815"
              ]
            },
            "minDurationMilliseconds": 600000
          },
          "outOfRoute": {
            "maxOffRouteMeters": 100,
            "minDurationMilliseconds": 600000
          },
          "outsideGeofence": {
            "location": {
              "addressIds": [
                "Placeat est voluptatem id tenetur amet.",
                "Omnis consectetur quis neque nihil molestiae harum."
              ],
              "addressTypes": [
                "agricultureSource",
                "unauthorizedZone",
                "undefined"
              ],
              "circle": {
                "name": "My Geofence Cirlce",
                "radiusMeters": 23,
                "latitude": 37.7749,
                "longitude": 137.7749
              },
              "polygon": {
                "name": "My Geofence Polygon",
                "vertices": [
                  {
                    "latitude": 37.7749,
                    "longitude": 137.7749
                  }
                ]
              },
              "tagIds": [
                "4815",
                "4815",
                "4815",
                "4815"
              ]
            },
            "minDurationMilliseconds": 600000
          },
          "panicButton": {
            "isFilteringOutPowerLoss": true
          },
          "reading": {
            "entityType": "Asset",
            "id": "engineTemperature",
            "minDurationMilliseconds": 600000,
            "continuousThreshold": {
              "operation": "GREATER",
              "threshold": 20,
              "unit": "celsius",
              "upperThreshold": 30
            },
            "enumThreshold": {
              "number": 2,
              "symbol": "HIGH"
            }
          },
          "routeStopEstimatedArrival": {
            "alertBeforeArrivalMilliseconds": 300000,
            "location": {
              "addressIds": [
                "Placeat est voluptatem id tenetur amet.",
                "Omnis consectetur quis neque nihil molestiae harum."
              ],
              "addressTypes": [
                "agricultureSource",
                "unauthorizedZone",
                "undefined"
              ],
              "circle": {
                "name": "My Geofence Cirlce",
                "radiusMeters": 23,
                "latitude": 37.7749,
                "longitude": 137.7749
              },
              "polygon": {
                "name": "My Geofence Polygon",
                "vertices": [
                  {
                    "latitude": 37.7749,
                    "longitude": 137.7749
                  }
                ]
              },
              "tagIds": [
                "4815",
                "4815",
                "4815",
                "4815"
              ]
            },
            "hasLiveShareLink": true,
            "isAlertOnRouteStopOnly": true
          },
          "safetyBehavior": {
            "behaviors": [
              "UnsafeParking",
              "HarshTurn",
              "CustomerCustomEvent6",
              "EatingDrinking"
            ],
            "behaviorCount": {
              "comparison": "EQUAL_TO",
              "numBehaviors": 10,
              "numDays": 30
            },
            "drivers": {
              "driverIds": [
                "12434",
                "12434",
                "12434"
              ],
              "tagIds": [
                "12434",
                "12434",
                "12434",
                "12434"
              ]
            },
            "safetyScore": {
              "comparison": "EQUAL_TO",
              "score": 60
            },
            "severities": [
              "medium",
              "medium",
              "medium"
            ],
            "statuses": [
              "NEEDS_RECOGNITION",
              "NEEDS_COACHING",
              "RECOGNIZED",
              "NEEDS_COACHING"
            ]
          },
          "scheduledMaintenance": {
            "dueInDays": 10,
            "scheduleId": "123"
          },
          "scheduledMaintenanceByEngineHours": {
            "dueInHours": 5000,
            "scheduleId": "123"
          },
          "scheduledMaintenanceOdometer": {
            "dueInMeters": 5000,
            "scheduleId": "123"
          },
          "speed": {
            "minDurationMilliseconds": 600000,
            "operation": "GREATER",
            "speedKilometersPerHour": 120
          },
          "suddenFuelLevelDrop": {
            "minFuelLevelChangeInPercents": 6
          },
          "suddenFuelLevelRise": {
            "minFuelLevelChangeInPercents": 6
          },
          "tireFaultCode": {
            "manufacturer": "MANUFACTURER_BENDIX",
            "hasCautionaryTireFaultCodes": true,
            "hasCriticalTireFaultCodes": true,
            "specificTireFaultCodes": [
              "TIRE_ALERT_ACROSS_AXLE_FAULT",
              "TIRE_ALERT_ACROSS_AXLE_FAULT",
              "TIRE_ALERT_ACROSS_AXLE_FAULT",
              "TIRE_ALERT_ACROSS_AXLE_FAULT"
            ]
          },
          "trainingAssignmentNearDueDate": {
            "conditionUnits": "DAYS",
            "conditionValue": 1,
            "timezone": "America/Los_Angeles",
            "assignmentGroups": [
              {
                "assignmentGroupType": "CATEGORY",
                "assignmentGroupUuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
              }
            ]
          },
          "unassignedDriving": {
            "minDurationMilliseconds": 600000
          },
          "vehicleBatteryVoltage": {
            "batteryVolts": 100,
            "minDurationMilliseconds": 600000,
            "operation": "GREATER"
          },
          "vehicleFaultCode": {
            "hasAnyAmberWarningLampCodes": true,
            "hasAnyFaultCodes": true,
            "hasAnyMalfunctionIndicatorLampCodes": true,
            "hasAnyProtectionLampCodes": true,
            "hasAnyRedStopLampCodes": true,
            "hasAnyTrailerAbsLampCodes": true,
            "minDurationMilliseconds": 600000,
            "specificFaultCodes": [
              {
                "faultCode": "1067",
                "type": "J1939_SPN"
              }
            ]
          }
        }
      }
    ],
    "externalIds": {},
    "operationalSettings": {
      "timeRangeType": "activeBetween",
      "timeRanges": [
        {
          "daysOfWeek": [
            "THURSDAY",
            "TUESDAY"
          ],
          "endTime": "20:00",
          "startTime": "11:00",
          "timezone": "America/Los_Angeles"
        }
      ]
    }
  }
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

The configuration of a alert.

actions · object[] · required

An array of actions.

Show child attributes

isEnabled · boolean · default: true · required

Whether the alert is enabled or not.

Example:

true

name · string · required

The custom name of the configuration.

Example:

"My Harsh Event Alert"

scope · object · required

What the triggers are scoped to. These are the objects this alert applies to.

Show child attributes

triggers · object[] · required

An array of triggers.

Show child attributes

externalIds · object

A map of external ids

Show child attributes

operationalSettings · object

Settings on when the alert should be operational.

Show child attributes

Response

200

application/json

OK response.

data · object · required

The configuration of a alert.

Show child attributes