--- title: Create Alert slug: suite-documentation/zaHb-create-alert docTags: createdAt: 2026-08-26T08:46:37.817Z --- This endpoint creates an alert configuration for a test plan. Alerts can be created for execution start or execution completion events. For completion alerts, result statuses can be selected to define when the alert should be sent. *** ### Endpoint Information - **URL**: `{gateway-url}/alerts/plan/{planId}` - **Method**: `POST` - **Authentication**: Required (`Bearer Token`) ### Request Headers | Header | Required | Description | | --------------- | -------- | --------------------------------------------------------------------------- | | `Authorization` | Yes | Bearer token used for authentication. Example: `Bearer ` | | `Content-Type` | Yes | Must be `application/json`. | | `X-Company-Id` | Yes | The company ID used by the gateway to authorize and route the request. | ### Path Variables | Parameter | Type | Required | Description | | --------- | ---- | -------- | --------------------------------------------------- | | `planId` | Long | Yes | The ID of the test plan. Must be a positive number. | ### Request Body - Beginning of Execution ```json { "alertType": "EMAIL", "alertSendingStatus": "Beginning of the Each Execution", "target": "demo@testinium.com", "alertSendingStatusResults": [], "targetId": null, "targetType": null, "language": null, "targetTimeZone": null } ``` ### Request Body - End of Execution ```json { "alertType": "EMAIL", "alertSendingStatus": "End of the Each Execution", "target": "demo@testinium.com", "alertSendingStatusResults": [ "Test Successful", "Test Failed", "Test Unexecuted", "Test Stopped", "Test Error" ], "targetId": null, "targetType": null, "language": null, "targetTimeZone": null } ``` ### Request Body - Slack Alert ```json { "alertType": "SLACK", "alertSendingStatus": "Beginning of the Each Execution", "target": "qa-alerts", "alertSendingStatusResults": [], "targetId": "C0123456789", "targetType": "CHANNEL", "language": "en", "targetTimeZone": "Europe/Istanbul" } ``` ### Request Body Parameters | Field | Type | Required | Description | | --------------------------- | ---------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `alertType` | String | Yes | Alert channel. Active supported values are `EMAIL` and `SLACK`. | | `alertSendingStatus` | String | Yes | Defines when the alert is sent. Supported values are `Beginning of the Each Execution` and `End of the Each Execution`. | | `target` | String | Yes | Alert target. For email alerts, this is the recipient email address. For Slack alerts, this can be the target display name. | | `alertSendingStatusResults` | Array of strings | Conditional | Required when `alertSendingStatus` is `End of the Each Execution`. Must be empty when `alertSendingStatus` is `Beginning of the Each Execution`. | | `targetId` | String | Conditional | Required for `SLACK` alerts. Slack user or channel ID. | | `targetType` | String | Conditional | Required for `SLACK` alerts. Supported values: `USER`, `CHANNEL`. | | `language` | String | No | Language code for alert content. Example: `en`, `tr`. | | `targetTimeZone` | String | No | Time zone used for alert timestamps. Example: `Europe/Istanbul`. | ### Supported Result Statuses These values can be used in `alertSendingStatusResults` when `alertSendingStatus` is `End of the Each Execution`. | Value | Description | | ----------------- | --------------------------------------- | | `Test Successful` | Send alert for successful test results. | | `Test Failed` | Send alert for failed test results. | | `Test Unexecuted` | Send alert for unexecuted test results. | | `Test Stopped` | Send alert for stopped test results. | | `Test Error` | Send alert for error test results. | | `Test Timed Out` | Send alert for timed out test results. | ### Response Body ```json { "data": { "id": 173, "planId": 766, "alertType": "EMAIL", "target": "demo@testinium.com", "targetId": null, "targetType": null, "alertSendingStatus": "Beginning of the Each Execution", "alertSendingStatusResult": null, "language": null, "targetTimeZone": null, "enabled": true, "unsubscribeLinkEliminated": false } } ``` ### Response Body - Multiple Result Statuses When multiple result statuses are selected, multiple alert records can be created. The response groups the selected result statuses under `alertSendingStatusResult`. ```json { "data": { "id": 176, "planId": 766, "alertType": "EMAIL", "target": "demo@testinium.com", "targetId": null, "targetType": null, "alertSendingStatus": "End of the Each Execution", "alertSendingStatusResult": [ { "id": 174, "name": "Test Successful" }, { "id": 175, "name": "Test Failed" }, { "id": 176, "name": "Test Error" } ], "language": null, "targetTimeZone": null, "enabled": true, "unsubscribeLinkEliminated": false } } ``` ### Response Fields | Field | Type | Description | | -------------------------------------- | ---------------- | ----------------------------------------------------------------------------------------- | | `data` | Object | Created alert payload. | | `data.id` | Long | Alert ID. For grouped result alerts, this can represent one of the created alert records. | | `data.planId` | Long | Test plan ID related to the alert. | | `data.alertType` | String | Alert channel. Example: `EMAIL`, `SLACK`. | | `data.target` | String | Alert target. | | `data.targetId` | String | Slack target ID, if applicable. | | `data.targetType` | String | Slack target type, if applicable. | | `data.alertSendingStatus` | String | Execution status that triggers the alert. | | `data.alertSendingStatusResult` | Array of objects | Selected result statuses for completion alerts. | | `data.alertSendingStatusResult[].id` | Long | Alert record ID for the selected result status. | | `data.alertSendingStatusResult[].name` | String | Result status description. | | `data.language` | String | Alert language, if provided. | | `data.targetTimeZone` | String | Alert target time zone, if provided. | | `data.enabled` | Boolean | Indicates whether the alert is enabled. | | `data.unsubscribeLinkEliminated` | Boolean | Indicates whether the email unsubscribe link is eliminated. | ### Important Notes - `Beginning of the Each Execution` alerts must not include result statuses. - `End of the Each Execution` alerts must include at least one result status. - For `SLACK` alerts, both `targetId` and `targetType` are required. - Duplicate alerts are not allowed for the same plan, target, sending status, and result status. - The response does not include `result.code` or `result.message`. ### Error Response Format ```json { "instance": "/alerts/plan/766", "status": 409, "title": "Conflict", "type": "https://errors.testinium.com/exception", "timestamp": "2026-08-18T12:08:41.165927056Z", "errorType": "EXCEPTION", "errors": { "code": 400, "message": "Alert already exists for related plan, target : demo@testinium.com, status : Beginning of the Each Execution" } } ``` ### HTTP Error Codes | HTTP Code | Error Message | Description | | --------- | ----------------------- | -------------------------------------------------------------------------------------------------------------- | | `400` | `Bad Request` | Request body is invalid, malformed, contains missing required fields, or contains invalid alert status values. | | `401` | `Unauthorized` | Authentication is missing or invalid. | | `403` | `Forbidden` | User does not have permission for this operation or company. | | `404` | `Not Found` | Plan was not found or could not be accessed. | | `405` | `Method Not Allowed` | The endpoint was called with an unsupported HTTP method. | | `409` | `Conflict` | Same alert configuration already exists. | | `500` | `Internal Server Error` | An unexpected error occurred on the server side. | | `503` | `Service Unavailable` | Notification service, project service, or another downstream service is unavailable. | ### Application Error Codes | Code | HTTP Status | Source | Description | | ------- | ----------- | ----------------- | ----------------------------------------------------------------- | | `400` | `409` | Notification | Alert already exists. | | `10003` | `404` | Project | Test plan not found. | | `10001` | `401` | Gateway | Authentication is required. | | `10002` | `401` | Gateway | Token is invalid or cannot be verified. | | `10003` | `403` | Gateway | Authorization failed for the requested resource. | | `10004` | `400` | Gateway | A required header, such as `X-Company-Id`, is missing or invalid. | | `10008` | `503` | Gateway | Routed service is unavailable. | | `10007` | `503` | Common | Downstream service is unavailable. | | `20005` | `400` | Common Validation | Request body or path variable validation failed. | | `20008` | `400` | Common Validation | Path variable type is invalid. | | `20009` | `405` | Common Validation | HTTP method is not supported. | ### Example Request ```bash curl --location '{gateway-url}/alerts/plan/{planId}' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --header 'X-Company-Id: ' \ --data-raw '{ "alertType": "EMAIL", "alertSendingStatus": "Beginning of the Each Execution", "target": "demo@testinium.com", "alertSendingStatusResults": [], "targetId": null, "targetType": null, "language": null, "targetTimeZone": null }' ```