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.

location_state and location_city are not accepted when creating an alert. Use the Edit Alert endpoint to set them.

Request Example

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": "[e-mail]",
  "cc_emails": ["[e-mail]"],
  "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

You must save the alert ID in order to use the Edit Alert endpoint.

• 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

{
  "id": 12345,
  "email": "[e-mail]",
  "cc_emails": ["[e-mail]"],
  "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:

{
  "detail": "Invalid value for 'email'. Field required"
}

No search criteria was provided:

{
  "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:

{
  "detail": "Invalid value for 'location_state'. Extra inputs are not permitted"
}

The equipment type is not valid:

{
  "detail": "Invalid equipment_type 'XYZ'"
}

The trailer logo is not valid:

{
  "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:

{
  "detail": "Could not create hot alert. [e-mail] already has 5, the user is limited to 5"
}

401 Unauthorized

{
  "message": "Access-Token header is missing",
  "error_type": "TokenMissingError",
  "error_code": "TOKEN_MISSING"
}

{
  "message": "Authentication token has expired",
  "error_type": "TokenExpiredError",
  "error_code": "TOKEN_EXPIRED"
}

403 Forbidden

{
  "message": "User not allowed to access this endpoint",
  "error_type": "PermissionError",
  "error_code": "PERMISSION_DENIED"
}

Create alert

post

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.

Authorizations

Access-TokenstringRequired

JWT provided directly in the Access-Token header. No "Bearer" prefix.

x-api-keystringRequired

API key provided by GenLogs.

Body

emailstring · emailRequired

Email address that receives the alert results. Must belong to a user of your company.

alert_namestring · min: 1Required

Name of the alert. Cannot be empty.

alert_typestring · enumOptional

normal runs once per day; hot runs every 15 minutes. The number of active hot alerts per user is limited.

Default: normalPossible values:

disabledbooleanOptional

Set to true to create the alert paused.

Default: false

cc_emailsstring · email[] · nullableOptional

Additional email addresses. Must be an array, even for a single address.

usdot_numberstring · nullableOptional

Search criteria – USDOT number of the carrier.

mc_numberstring · nullableOptional

Search criteria – MC number of the carrier.

license_platestring · nullableOptional

Search criteria – license plate of the vehicle.

vinstring · nullableOptional

Search criteria – last 6 digits of the vehicle identification number.

cab_numberstring · nullableOptional

Search criteria – cab number of the vehicle.

equipment_typestring · enum · nullableOptional

Search criteria – equipment type. Case-insensitive.

Possible values:

trailer_logostring · nullableOptional

Search criteria – trailer logo. Must be a value returned by the List logos endpoint.

trailer_numberstring · nullableOptional

Search criteria – trailer number.

exact_match_trailer_numberbooleanOptional

true matches the trailer number exactly; false uses a "contains" search.

Default: false

chassis_numberstring · nullableOptional

Search criteria – chassis number.

exact_match_chassis_numberbooleanOptional

true matches the chassis number exactly; false uses a "contains" search.

Default: false

container_numberstring · nullableOptional

Search criteria – container number.

exact_match_container_numberbooleanOptional

true matches the container number exactly; false uses a "contains" search.

Default: false

deep_searchstring · nullableOptional

Search criteria – free-text deep search.

exact_match_deep_searchbooleanOptional

true matches the deep search criteria exactly; false uses a "contains" search.

Default: false

Responses

200

Alert created successfully.

application/json

idintegerOptionalExample: 12345

emailstringOptionalExample: [e-mail]

cc_emailsstring[] · nullableOptionalExample: ["[e-mail]"]

alert_namestringOptionalExample: New alert

alert_typestringOptionalExample: normal

disabledbooleanOptionalExample: false

notification_channelsstring[]OptionalExample: ["EMAIL"]

usdot_numberstring · nullableOptional

mc_numberstring · nullableOptional

license_platestring · nullableOptional

vinstring · nullableOptional

cab_numberstring · nullableOptional

equipment_typestring · nullableOptional

trailer_logostring · nullableOptional

logo_op_typestring · nullableOptional

Reserved for internal use.

trailer_numberstring · nullableOptionalExample: 12345

exact_match_trailer_numberbooleanOptionalExample: false

chassis_numberstring · nullableOptional

exact_match_chassis_numberbooleanOptionalExample: false

container_numberstring · nullableOptional

exact_match_container_numberbooleanOptionalExample: false

deep_searchstring · nullableOptional

exact_match_deep_searchbooleanOptionalExample: false

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.

application/json

401

Unauthorized – Access-Token is missing, invalid, or expired.

application/json

403

Forbidden – the user lacks the required permission.

application/json

500

Internal Server Error.

post/alerts

POST /alerts HTTP/1.1
Host: api.genlogs.io
Access-Token: YOUR_API_KEY
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 193

{
  "email": "[e-mail]",
  "cc_emails": [
    "[e-mail]"
  ],
  "alert_name": "New alert",
  "alert_type": "normal",
  "disabled": false,
  "trailer_number": "12345",
  "exact_match_trailer_number": false
}

{
  "id": 12345,
  "email": "[e-mail]",
  "cc_emails": [
    "[e-mail]"
  ],
  "alert_name": "New alert",
  "alert_type": "normal",
  "disabled": false,
  "notification_channels": [
    "EMAIL"
  ],
  "usdot_number": "text",
  "mc_number": "text",
  "license_plate": "text",
  "vin": "text",
  "cab_number": "text",
  "equipment_type": "text",
  "trailer_logo": "text",
  "logo_op_type": "text",
  "trailer_number": "12345",
  "exact_match_trailer_number": false,
  "chassis_number": "text",
  "exact_match_chassis_number": false,
  "container_number": "text",
  "exact_match_container_number": false,
  "deep_search": "text",
  "exact_match_deep_search": false
}