> For the complete documentation index, see [llms.txt](https://docs.genlogs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.genlogs.io/alerts/create-alert.md). # Create alert This endpoint is restricted to authorized users with appropriate permissions. Create Alert endpoint allows our customers to create alerts that are triggered when one of GenLogs sensors detects a truck that matches the alert criteria, sending the detection results by email or webhook. ### Authentication Include the following headers in your requests: * **Access-Token**: The access token obtained from the "Create Access Token" endpoint. * **x-api-key**: The API key provided by GenLogs. This header must be included in the request. ### Permissions Make sure that your API user is created with a role that has the `create-alert-endpoint` permission. ### Endpoint * **URL**: `https://api.genlogs.io/alerts` * **Method**: `POST` ### Request Format All parameters must be sent as JSON in the request body with the `Content-Type: application/json` header. ### Request Body Content Only `email` and `alert_name` are required. Any field not listed here is rejected with a 400. * **email** (string, required): Email address that receives the alert results. It must belong to a user of your company. * **alert\_name** (string, required): Name of the alert. Cannot be empty. * **alert\_type** (string, optional, default `normal`): Type of alert. * **normal**: Also called "Daily Alerts", triggered once per day in the morning. * **hot**: Triggered every 15 minutes. The number of active hot alerts per user is limited. * **disabled** (boolean, optional, default `false`): Set to `true` to create the alert paused. * **cc\_emails** (array of strings, optional): Additional email addresses that receive the alert results. Must be an array, even for a single address. * **notification\_channels** (array of strings, optional, default `["EMAIL"]`): Channels that receive the alert results: `EMAIL`, `WEBHOOK`. Case-insensitive. **Search criteria** – at least one of the following fields must have a value: * **usdot\_number** (string, optional): USDOT number of the carrier. * **mc\_number** (string, optional): MC number of the carrier. * **license\_plate** (string, optional): License plate of the vehicle. * **vin** (string, optional): Last 6 digits of the vehicle identification number. * **cab\_number** (string, optional): Cab number of the vehicle. * **equipment\_type** (string, optional): Equipment type. Allowed values: `BELLY DUMP`, `BOX TRUCK`, `CAR HAULER`, `CARGO TRAILER`, `CONESTOGA`, `DAY CAB`, `DOUBLE PUP`, `DRY BULK`, `DRY VAN`, `DUMP`, `END DUMP`, `FIXED GOOSENECK LOWBOY`, `FLATBED`, `HIGH TONNAGE TRAILER`, `HOPPER`, `HOTSHOT`, `INTERMODAL`, `LIVESTOCK TRAILER`, `LOGGING`, `LOWBOY RGN`, `MOFFETT`, `OTHER`, `REEFER`, `SLEEPER CAB`, `STEP DECK`, `TANKER`, `WRECKER`. Case-insensitive. * **trailer\_logo** (string, optional): Logo displayed on the trailer. Must be one of the values returned by the List logos endpoint. * **trailer\_number** (string, optional): Trailer number. * **exact\_match\_trailer\_number** (boolean, optional, default `false`): `true` matches the trailer number exactly; `false` uses a "contains" search. * **chassis\_number** (string, optional): Chassis number. * **exact\_match\_chassis\_number** (boolean, optional, default `false`): `true` matches the chassis number exactly; `false` uses a "contains" search. * **container\_number** (string, optional): Container number. * **exact\_match\_container\_number** (boolean, optional, default `false`): `true` matches the container number exactly; `false` uses a "contains" search. * **deep\_search** (string, optional): Free-text deep search criteria. * **exact\_match\_deep\_search** (boolean, optional, default `false`): `true` matches the deep search criteria exactly; `false` uses a "contains" search. {% hint style="info" %} `location_state` and `location_city` are not accepted when creating an alert. Use the Edit Alert endpoint to set them. {% endhint %} ### Request Example ```bash curl -X POST 'https://api.genlogs.io/alerts' \ -H 'Access-Token: {access_token}' \ -H 'x-api-key: {your_api_key}' \ -H 'Content-Type: application/json' \ -d '{ "email": "user@example.com", "cc_emails": ["notification@example.com"], "alert_name": "New alert", "alert_type": "normal", "disabled": false, "trailer_number": "12345", "exact_match_trailer_number": false }' ``` ### Response Codes * **200 OK**: The alert was created. * **400 Bad Request**: A field is missing, invalid, or not allowed, no search criteria was provided, the trailer logo is not valid, or the hot alert limit was reached. * **401 Unauthorized**: The Access-Token is missing, invalid, or expired. * **403 Forbidden**: The API key is missing or invalid, or your user does not have the required permission. * **500 Internal Server Error**: An issue occurred on the server. ### Response Body {% hint style="info" %} You must save the alert ID in order to use the `Edit Alert` endpoint. {% endhint %} * **id** (integer): Unique identifier of the alert. * **email** (string): Email address that receives the alert results. * **cc\_emails** (array of strings, nullable): Additional email addresses. * **alert\_name** (string): Name of the alert. * **alert\_type** (string): `normal` or `hot`. * **disabled** (boolean): Whether the alert is paused. * **notification\_channels** (array of strings): Channels that receive the alert results, in uppercase. * **usdot\_number**, **mc\_number**, **license\_plate**, **vin**, **cab\_number**, **equipment\_type**, **trailer\_logo**, **trailer\_number**, **chassis\_number**, **container\_number**, **deep\_search** (string, nullable): Search criteria of the alert. * **exact\_match\_trailer\_number**, **exact\_match\_chassis\_number**, **exact\_match\_container\_number**, **exact\_match\_deep\_search** (boolean): Match mode of each criteria. * **logo\_op\_type** (string, nullable): Reserved for internal use. 200 OK ```json { "id": 12345, "email": "user@example.com", "cc_emails": ["notification@example.com"], "alert_name": "New alert", "alert_type": "normal", "disabled": false, "notification_channels": ["EMAIL"], "usdot_number": null, "mc_number": null, "license_plate": null, "vin": null, "cab_number": null, "equipment_type": null, "trailer_logo": null, "logo_op_type": null, "trailer_number": "12345", "exact_match_trailer_number": false, "chassis_number": null, "exact_match_chassis_number": false, "container_number": null, "exact_match_container_number": false, "deep_search": null, "exact_match_deep_search": false } ``` 400 Bad Request A required field is missing: ```json { "detail": "Invalid value for 'email'. Field required" } ``` No search criteria was provided: ```json { "detail": "At least one optional field must be provided. Optional fields include: usdot_number, mc_number, license_plate, vin, cab_number, trailer_logo, trailer_number, chassis_number, container_number, deep_search, equipment_type." } ``` A field that is not allowed was sent: ```json { "detail": "Invalid value for 'location_state'. Extra inputs are not permitted" } ``` The equipment type is not valid: ```json { "detail": "Invalid equipment_type 'XYZ'" } ``` The trailer logo is not valid: ```json { "message": "The provided 'trailer_logo' 'XYZ' does not exist in the allowed logos", "error_type": "InvalidLogoError", "error_code": "INVALID_LOGO", "details": { "field": "trailer_logo", "value": "XYZ" } } ``` The hot alert limit was reached: ```json { "detail": "Could not create hot alert. user@example.com already has 5, the user is limited to 5" } ``` 401 Unauthorized ```json { "message": "Access-Token header is missing", "error_type": "TokenMissingError", "error_code": "TOKEN_MISSING" } ``` ```json { "message": "Authentication token has expired", "error_type": "TokenExpiredError", "error_code": "TOKEN_EXPIRED" } ``` 403 Forbidden ```json { "message": "User not allowed to access this endpoint", "error_type": "PermissionError", "error_code": "PERMISSION_DENIED" } ``` ## Create alert > Creates an alert that is triggered when a GenLogs sensor detects a truck matching its search criteria. Only \`email\` and \`alert\_name\` are required, and at least one search criteria field must have a value. \`email\` must belong to a user of the caller's company. Unknown properties are rejected.
```json {"openapi":"3.0.3","info":{"title":"Alerts API - Create Alert","version":"1.0.0"},"servers":[{"url":"https://api.genlogs.io"}],"security":[{"AccessTokenAuth":[],"ApiKeyAuth":[]}],"components":{"securitySchemes":{"AccessTokenAuth":{"type":"apiKey","in":"header","name":"Access-Token","description":"JWT provided directly in the Access-Token header. No \"Bearer\" prefix.\n"}},"schemas":{"CreateAlertRequest":{"type":"object","additionalProperties":false,"required":["email","alert_name"],"properties":{"email":{"type":"string","format":"email","description":"Email address that receives the alert results. Must belong to a user of your company."},"alert_name":{"type":"string","minLength":1,"description":"Name of the alert. Cannot be empty."},"alert_type":{"type":"string","enum":["normal","hot"],"default":"normal","description":"`normal` runs once per day; `hot` runs every 15 minutes. The number of active hot alerts per user is limited.\n"},"disabled":{"type":"boolean","default":false,"description":"Set to true to create the alert paused."},"cc_emails":{"type":"array","nullable":true,"items":{"type":"string","format":"email"},"description":"Additional email addresses. Must be an array, even for a single address."},"notification_channels":{"type":"array","items":{"type":"string","enum":["EMAIL","WEBHOOK"]},"default":["EMAIL"],"description":"Channels that receive the alert results. Case-insensitive."},"usdot_number":{"type":"string","nullable":true,"description":"Search criteria – USDOT number of the carrier."},"mc_number":{"type":"string","nullable":true,"description":"Search criteria – MC number of the carrier."},"license_plate":{"type":"string","nullable":true,"description":"Search criteria – license plate of the vehicle."},"vin":{"type":"string","nullable":true,"description":"Search criteria – last 6 digits of the vehicle identification number."},"cab_number":{"type":"string","nullable":true,"description":"Search criteria – cab number of the vehicle."},"equipment_type":{"type":"string","nullable":true,"description":"Search criteria – equipment type. Case-insensitive.","enum":["BELLY DUMP","BOX TRUCK","CAR HAULER","CARGO TRAILER","CONESTOGA","DAY CAB","DOUBLE PUP","DRY BULK","DRY VAN","DUMP","END DUMP","FIXED GOOSENECK LOWBOY","FLATBED","HIGH TONNAGE TRAILER","HOPPER","HOTSHOT","INTERMODAL","LIVESTOCK TRAILER","LOGGING","LOWBOY RGN","MOFFETT","OTHER","REEFER","SLEEPER CAB","STEP DECK","TANKER","WRECKER"]},"trailer_logo":{"type":"string","nullable":true,"description":"Search criteria – trailer logo. Must be a value returned by the List logos endpoint."},"trailer_number":{"type":"string","nullable":true,"description":"Search criteria – trailer number."},"exact_match_trailer_number":{"type":"boolean","default":false,"description":"true matches the trailer number exactly; false uses a \"contains\" search."},"chassis_number":{"type":"string","nullable":true,"description":"Search criteria – chassis number."},"exact_match_chassis_number":{"type":"boolean","default":false,"description":"true matches the chassis number exactly; false uses a \"contains\" search."},"container_number":{"type":"string","nullable":true,"description":"Search criteria – container number."},"exact_match_container_number":{"type":"boolean","default":false,"description":"true matches the container number exactly; false uses a \"contains\" search."},"deep_search":{"type":"string","nullable":true,"description":"Search criteria – free-text deep search."},"exact_match_deep_search":{"type":"boolean","default":false,"description":"true matches the deep search criteria exactly; false uses a \"contains\" search."}}},"CreateAlertResponse":{"type":"object","properties":{"id":{"type":"integer"},"email":{"type":"string"},"cc_emails":{"type":"array","nullable":true,"items":{"type":"string"}},"alert_name":{"type":"string"},"alert_type":{"type":"string"},"disabled":{"type":"boolean"},"notification_channels":{"type":"array","items":{"type":"string"}},"usdot_number":{"type":"string","nullable":true},"mc_number":{"type":"string","nullable":true},"license_plate":{"type":"string","nullable":true},"vin":{"type":"string","nullable":true},"cab_number":{"type":"string","nullable":true},"equipment_type":{"type":"string","nullable":true},"trailer_logo":{"type":"string","nullable":true},"logo_op_type":{"type":"string","nullable":true,"description":"Reserved for internal use."},"trailer_number":{"type":"string","nullable":true},"exact_match_trailer_number":{"type":"boolean"},"chassis_number":{"type":"string","nullable":true},"exact_match_chassis_number":{"type":"boolean"},"container_number":{"type":"string","nullable":true},"exact_match_container_number":{"type":"boolean"},"deep_search":{"type":"string","nullable":true},"exact_match_deep_search":{"type":"boolean"}}},"DetailError":{"type":"object","properties":{"detail":{"type":"string"}}},"ApiError":{"type":"object","properties":{"message":{"type":"string"},"error_type":{"type":"string"},"error_code":{"type":"string"},"details":{"type":"object"}}}}},"paths":{"/alerts":{"post":{"summary":"Create alert","description":"Creates an alert that is triggered when a GenLogs sensor detects a truck matching its search criteria. Only `email` and `alert_name` are required, and at least one search criteria field must have a value. `email` must belong to a user of the caller's company. Unknown properties are rejected.\n","operationId":"createAlert","tags":["Alerts"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAlertRequest"}}}},"responses":{"200":{"description":"Alert created successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAlertResponse"}}}},"400":{"description":"Bad Request – a field is missing, invalid, or not allowed, no search criteria was provided, the trailer logo is not valid, or the hot alert limit was reached.\n","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/DetailError"},{"$ref":"#/components/schemas/ApiError"}]}}}},"401":{"description":"Unauthorized – Access-Token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Forbidden – the user lacks the required permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal Server Error."}}}}}} ```