Create Alert
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 <your_access_token> |
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
{
"alertType": "EMAIL",
"alertSendingStatus": "Beginning of the Each Execution",
"target": "[email protected]",
"alertSendingStatusResults": [],
"targetId": null,
"targetType": null,
"language": null,
"targetTimeZone": null
}Request Body - End of Execution
{
"alertType": "EMAIL",
"alertSendingStatus": "End of the Each Execution",
"target": "[email protected]",
"alertSendingStatusResults": [
"Test Successful",
"Test Failed",
"Test Unexecuted",
"Test Stopped",
"Test Error"
],
"targetId": null,
"targetType": null,
"language": null,
"targetTimeZone": null
}Request Body - Slack Alert
{
"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
{
"data": {
"id": 173,
"planId": 766,
"alertType": "EMAIL",
"target": "[email protected]",
"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.
{
"data": {
"id": 176,
"planId": 766,
"alertType": "EMAIL",
"target": "[email protected]",
"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
{
"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 : [email protected], 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
curl --location '{gateway-url}/alerts/plan/{planId}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <your_access_token>' \
--header 'X-Company-Id: <company_id>' \
--data-raw '{
"alertType": "EMAIL",
"alertSendingStatus": "Beginning of the Each Execution",
"target": "[email protected]",
"alertSendingStatusResults": [],
"targetId": null,
"targetType": null,
"language": null,
"targetTimeZone": null
}'