Create Alert

16 min

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
  }'