--- updatedAt: 2026-05-27T10:18:53.000Z agentTools: projectIndex: https://gethapn.readme.io/llms.txt --- # Create a client alert configuration Create a client alert configuration. # OpenAPI definition ```json { "openapi": "3.0.3", "info": { "description": "The Hapn API is an HTTP interface for managing devices, accounts, and cloud data.", "version": "1.0.0", "title": "Hapn API", "termsOfService": "https://gethapn.com/terms", "contact": { "name": "Dev", "email": "developer@gethapn.com", "url": "http://gethapn.com" }, "license": { "name": "Apache 2.0", "url": "http://www.apache.org/licenses/LICENSE-2.0.html" } }, "servers": [ { "url": "https://api.iotgps.io/v1", "description": "Prod" }, { "url": "https://api-dev.iotgps.io/v1", "description": "Dev" } ], "paths": { "/client-alerts/configurations": { "post": { "summary": "Create a client alert configuration", "tags": [ "Alerts" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateClientAlertConfigurationBody" } } } }, "responses": { "200": { "description": "The created client alert configuration.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/ClientAlertConfiguration" } } } ] }, "examples": { "example-1": { "value": { "success": true, "message": "ok", "result": { "alertConfigurationId": 1, "clientId": 123, "status": "active", "alertType": { "id": 1, "name": "Movement" }, "name": "Movement 1", "description": "Movement description", "alertValue": "value", "alertMetadata": "metadata", "readOnly": false } } } } } } }, "400": { "$ref": "#/components/responses/UnschedulableAlert" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/Error" } }, "operationId": "create-client-alert-configuration", "description": "Create a client alert configuration.\n" } } }, "components": { "schemas": { "AlertFilterDaysOfWeekProp": { "type": "string", "description": "A 7 digit binary number. Ex: 1111111. Each digit represents a day of week. 1 means enabled, 0 means not disabled. 1st digit represents Sunday, 2nd digit represents Monday and so on ending with 7th digit representing Saturday" }, "AlertFilterStartTimeProp": { "type": "string", "description": "Start time of the time window. Format: HH:mm" }, "AlertFilterEndTimeProp": { "type": "string", "description": "Start time of the time window. Format: HH:mm" }, "AlertConfigFilterTimeSegment": { "description": "A time segment to apply specific filter conditions by time and day of the week", "type": "object", "x-examples": { "example-1": { "daysOfWeek": "1111111", "startTime": "00:00", "endTime": "23:59" } }, "title": "", "properties": { "daysOfWeek": { "$ref": "#/components/schemas/AlertFilterDaysOfWeekProp" }, "startTime": { "$ref": "#/components/schemas/AlertFilterStartTimeProp" }, "endTime": { "$ref": "#/components/schemas/AlertFilterEndTimeProp" } } }, "AlertConfigFilter": { "description": "A filter to apply specific conditions to the user alert settings", "type": "object", "x-examples": { "example-1": { "imeis": [ "868239050345326" ], "timeSegmentsType": "custom", "timeSegments": [ { "daysOfWeek": "1111111", "startTime": "00:00", "endTime": "23:59" } ] }, "example-2": { "imeis": [ "868239050345326" ], "timeSegmentsType": "afterHours" } }, "title": "", "properties": { "imeis": { "type": "array", "description": "IMEI list of the devices to apply the filter. If no IMEI is provided, the filter will be applied to all devices.", "items": { "type": "string" } }, "timeSegmentsType": { "type": "string", "nullable": true, "enum": [ "always", "business", "afterHours", "custom", "weekdays", "weekends" ], "description": "Which schedule the alert follows.\n\nFor `business` and `afterHours` the schedule is DERIVED from the account's business hours and\n`timeSegments` is ignored on the way in: whatever you send is discarded and replaced with the\naccount's own hours (`business`) or the complement of them across the week (`afterHours`). The\nstored schedule is then kept current automatically — editing the account's business hours\nre-derives every alert configuration that uses one of these two values. An account with no\nbusiness hours configured falls back to 08:00-17:00 Monday to Friday.\n\nFor `always`, `custom`, `weekdays` and `weekends` the `timeSegments` you send ARE the schedule,\nstored as sent and never rewritten. `weekdays` and `weekends` are legacy values kept for older\nmobile clients; prefer `custom`.\n\nOmit the field to leave the alert unscoped. On update, omitting it keeps whatever is stored —\nsend `null` explicitly to clear it.\n" }, "timeSegments": { "type": "array", "description": "The time windows in which the alert may fire, in the device's local time. Both ends are\nINCLUSIVE, so `08:00`-`17:00` includes the whole of minute 17:00. Ignored when\n`timeSegmentsType` is `business` or `afterHours` — see that field.\n", "items": { "$ref": "#/components/schemas/AlertConfigFilterTimeSegment" } } } }, "CreateClientAlertConfigurationBody": { "description": "The client alert configuration definition", "type": "object", "x-examples": { "example-1": { "name": "Speeding 50 km/h", "alertName": "Speeding", "alertValue": "50", "alertMetadata": "{\"speed\": \"50\"}", "filter": { "imei": "868239050345326", "timeSegments": [ { "daysOfWeek": "1111111", "startTime": "00:00", "endTime": "23:59" } ] } } }, "properties": { "name": { "type": "string" }, "alertName": { "$ref": "#/components/schemas/AlertName" }, "alertValue": { "type": "string" }, "alertMetadata": { "type": "string" }, "filter": { "$ref": "#/components/schemas/AlertConfigFilter" } } }, "SuccessResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "result": { "type": "object" } }, "required": [ "message", "success" ], "x-examples": { "example-1": { "value": { "success": true, "message": "ok", "result": { "imei": "12345" } } } } }, "ErrorResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "success", "message" ], "x-examples": { "example-1": { "value": { "success": false, "message": "Unauthorized" } } } }, "AlertName": { "description": "The alert type name", "type": "string", "default": null, "enum": [ "Speeding", "SOS", "LowBattery", "GeofenceEntry", "GeofenceExit", "Movement", "IgnitionOn", "IgnitionOff", "TripStarted", "TripFinished", "TripExceedsDistance", "TripExceedsDuration", "StartedCharging", "StoppedCharging", "PluggedExternalPowerSource", "UnpluggedExternalPowerSource", "Offline", "Online", "LightTamperStarted", "LightTamperEnded", "PowerOff", "PowerOn", "LowExternalVoltage", "HighExternalVoltage", "LowExternalBattery" ] }, "ClientAlertConfiguration": { "description": "A client alert configuration", "type": "object", "x-examples": { "example-1": { "alertConfigurationId": 1, "clientId": 123, "status": "active", "alertType": { "id": 1, "alertName": "Movement" }, "name": "Movement 1", "description": "Movement description", "alertValue": "value", "alertMetadata": "metadata", "readOnly": false, "allUsersInAccountRecipientConfig": { "id": 1, "emailNotification": true, "smsNotification": false, "appNotification": true, "pushNotification": false, "isEnabled": true }, "internalUserRecipients": [ { "id": 2, "userId": "2a75189d-b5f4-4be6-9b3b-0552615e4494", "isEnabled": true, "smsNotification": true, "emailNotification": false, "appNotification": false, "pushNotification": false } ], "internalRoleRecipients": [ { "id": 3, "role": "admin", "isEnabled": true, "smsNotification": false, "emailNotification": true, "appNotification": false, "pushNotification": false } ], "externalRecipients": [ { "id": 1, "notificationType": "email", "recipient": "useremail@mail.com", "isEnabled": true } ] } }, "title": "", "properties": { "alertConfigurationId": { "type": "number", "description": "The alert configuration identifier" }, "clientId": { "type": "number", "description": "The client identifier" }, "status": { "type": "string", "description": "The alert configuration status", "enum": [ "active", "deleted" ] }, "alertType": { "type": "object", "description": "The alert type", "properties": { "id": { "type": "number", "description": "The alert type identifier" }, "name": { "type": "string", "description": "The alert type name" } }, "required": [ "id", "name" ] }, "name": { "type": "string", "description": "The alert configuration name" }, "description": { "type": "string", "description": "The alert configuration description" }, "alertValue": { "type": "string", "description": "The alert value" }, "alertMetadata": { "type": "string", "description": "The alert metadata" }, "readOnly": { "type": "boolean", "description": "Determines if the alert configuration is read only" }, "allUsersInAccountRecipientConfig": { "type": "object", "description": "The alert notifications config for all users in account", "properties": { "id": { "type": "number", "description": "The recipient identifier" }, "emailNotification": { "type": "boolean", "description": "Determines if the recipient receives email notifications" }, "smsNotification": { "type": "boolean", "description": "Determines if the recipient receives sms notifications" }, "appNotification": { "type": "boolean", "description": "Determines if the recipient receives app notifications" }, "pushNotification": { "type": "boolean", "description": "Determines if the recipient receives push notifications" }, "isEnabled": { "type": "boolean", "description": "Determines if the configuration is enabled" } } }, "internalUserRecipients": { "type": "array", "description": "The alert configuration internal user recipients", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "The recipient identifier" }, "userId": { "type": "string", "description": "The recipient user identifier" }, "isEnabled": { "type": "boolean", "description": "Determines if the recipient is enabled" }, "smsNotification": { "type": "boolean", "description": "Determines if the recipient receives sms notifications" }, "emailNotification": { "type": "boolean", "description": "Determines if the recipient receives email notifications" }, "appNotification": { "type": "boolean", "description": "Determines if the recipient receives app notifications" }, "pushNotification": { "type": "boolean", "description": "Determines if the recipient receives push notifications" } } } }, "internalRoleRecipients": { "type": "array", "description": "The alert configuration internal role recipients", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "The recipient identifier" }, "role": { "type": "string", "description": "The recipient role name" }, "isEnabled": { "type": "boolean", "description": "Determines if the recipient is enabled" }, "smsNotification": { "type": "boolean", "description": "Determines if the recipient receives sms notifications" }, "emailNotification": { "type": "boolean", "description": "Determines if the recipient receives email notifications" }, "appNotification": { "type": "boolean", "description": "Determines if the recipient receives app notifications" }, "pushNotification": { "type": "boolean", "description": "Determines if the recipient receives push notifications" } } } }, "externalRecipients": { "type": "array", "description": "The alert configuration external recipients", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "The recipient identifier" }, "notificationType": { "type": "string", "description": "The recipient notification type" }, "recipient": { "type": "string", "description": "The recipient email or phone number" }, "isEnabled": { "type": "boolean", "description": "Determines if the recipient is enabled" } } } } }, "required": [ "alertConfigurationId", "clientId", "status", "alertType", "alertValue", "alertMetadata", "readOnly", "internalRecipients", "externalRecipients" ] } }, "responses": { "Unauthorized": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example-1": { "value": { "success": false, "message": "Unauthorized" } } } } } }, "Error": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example-1": { "value": { "success": false, "message": "Error" } } } } } }, "UnschedulableAlert": { "description": "The requested schedule leaves the alert no time in which it could ever fire. Returned when\n`filter.timeSegmentsType` is `afterHours` on an account whose business hours cover the entire week,\nso the complement is empty. Widen the account's business hours or pick a different schedule.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example-1": { "value": { "success": false, "message": "Business hours cover the entire week, so an \"Outside Business Hours\" alert has no time in which it could fire" } } } } } } }, "securitySchemes": { "OAuth2": { "type": "oauth2", "flows": { "clientCredentials": { "tokenUrl": "https://auth.usehapn.com/oauth2/token", "scopes": {} } } } } }, "tags": [ { "name": "Alerts", "description": "Alerts configurations" } ], "security": [ { "OAuth2": [] } ] } ```