---
title: "Creates a rule"
method: POST
path: "/rules/v4"
tags: ["Rules"]
---

# Creates a rule

`POST /rules/v4`

Creates a rule of the specified rule `type` and with the defined `threshold`.
After the rule has been created, it needs to be associated to a device to get activated.

Detention rule
---
For a rule of the `detention` type the threshold is defined as a duration in seconds.
A `DETENTION_STARTED` event gets triggered when the device has remained
stationary for longer than the threshold duration.
A `DETENTION_ENDED` event will be generated when the device starts moving again.

Utilization rule
---
For a rule of the `utilization` type the threshold is defined as a duration in seconds.
An `UNUTILIZED` event will
be generated when the device has been stationary for longer than the threshold duration, 
and `UTILIZED` event gets triggered when the device starts moving again after having been stationary.

Dwelling rule
---
For a rule of the `dwelling` type the threshold is defined as a duration in seconds.
A `DWELLING_STARTED` event gets triggered when a dwelling time of the device
inside any device-associated geofence exceeds the threshold duration.
When the device exits the geofence, a `DWELLING_ENDED` event will be generated.

Online rule
---
For a rule of the `online` type there is no threshold defined.
A `TRUE_TO_FALSE` event gets triggered when the
device is late for the planned ingestion schedule by more than 5 minutes.
A `FALSE_TO_TRUE` event is generated when the device starts ingesting again after having been offline.
The planned ingestion schedule needs to be configured in the device `desired shadow`
(the `desired.system.rate.sendMs` property).

Stock rule
---
For a rule of the `stock` type the threshold is defined as `minVolume` and/or `maxVolume` values.
When creating a stock rule, also a geofence ID needs to be specified.
When the number of devices inside the specified geofence exceeds `maxVolume`, an `OVERSTOCK`
event will be generated. Similarly, when the number of devices inside the specified geofence
gets below `minVolume`, an `UNDERSTOCK` event will be generated. When the number of
devices inside the specified geofence is between `minVolume` and `maxVolume`, a `NORMAL_VOLUME`
event will be generated. Note that the stock rule only gets triggered for devices that are associated
to the specified geofence.

Shipment schedule rule
---
For a rule of the `shipmentSchedule` type there are `before` and `after` deviation time thresholds 
from the planned shipment ETD/ETA.
A `SHIPMENT_EARLY` event gets triggered when the shipment is ahead
of schedule by the number of `before` seconds.
A `SHIPMENT_DELAYED` event gets triggered when the shipment is behind
schedule by the number of `after` seconds.
A `SHIPMENT_ON_TIME` event gets triggered when the shipment is on time.

When a rule has been successfully created, the response body will contain the created rule ID.

## Request body

- union
  - object
    - `description` string — Rule description
    - `name` string — Rule name
    - `threshold` object, required — Utilization event is triggered when the asset starts moving indicating that the asset is utilized, and also when the asset stops moving and has been stationary for longer than the threshold duration indicating that the asset is unutilized.
      - `durationS` integer, required — Duration in seconds
    - `type` 'utilization', required — The rule type
  - object
    - `description` string — Rule description
    - `name` string — Rule name
    - `threshold` object, required — Detention event is triggered when the asset has been continuously stationary for longer than the threshold duration.
      - `durationS` integer, required — Duration in seconds
    - `type` 'detention', required — The rule type
  - object
    - `description` string — Rule description
    - `name` string — Rule name
    - `threshold` object, required — Dwelling event is triggered when the asset has been continuously inside a geofence for longer than the threshold duration.
      - `durationS` integer, required — Duration in seconds
    - `type` 'dwelling', required — The rule type
  - object
    - `description` string — Rule description
    - `geofenceId` string, uuid, required — Geofence ID
    - `name` string — Rule name
    - `threshold` object, required
      - `maxVolume` integer — A maximum volume of stock
      - `minVolume` integer — A minimum volume of stock
    - `type` 'stock', required — The rule type
  - object
    - `description` string — Rule description
    - `name` string — Rule name
    - `type` 'online', required — The rule type
  - object
    - `description` string — Rule description
    - `name` string — Rule name
    - `threshold` object, required
      - `after` integer — Allowed time deviation in seconds from the planned ETD/ETA in case the shipment is behind the schedule
      - `before` integer — Allowed time deviation in seconds from the planned ETD/ETA in case the shipment is ahead of schedule
    - `type` 'shipmentSchedule', required — The rule type

## Response `201`

Created

The rule was successfully created.

- object
  - `ruleId` string, uuid, required — Must be a valid UUIDv4.

## Other responses

- `400` — Bad request The request object is in an incorrect format or has values that are invalid or out of range. If available, further error details are provided in the response body.
- `401` — Unauthorized The request did not provide correct authentication details
- `403` — Forbidden The account does not have the correct privileges

---

[API](https://skmtc.net/here/apis/tracking.md) · [All operations](https://skmtc.net/here/apis/tracking/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/here/tracking/revisions/efa162f7023c/schema)