Notification Rule API

🚧
If using the EU instance of Opsgenie, the URL needs to be https://api.eu.opsgenie.com for requests to be successful.

General Information

Domains

Notification Rule Steps

📘
Create an API Integration and obtain your apiKey to make requests listed above. Please make sure that the integration is not restricted to access configurations.

📘
You can refer Create and manage notification preferences
for detailed information about the notification rules and their steps

Create Notification Rule

Create notification rule is a write request. If the integration of the API key configured as read-only, the request will not be accepted. For more information, you can refer to API Access Management

HTTP Method	URL
POST	https://api.opsgenie.com/v2/users/:userIdentifier/notification-rules

In-Line Parameters

Referred Name	Description
userIdentifier	Identifier of the user for this notification rule. You should provide either id or username of the user

JSON Body Fields

Field	Mandatory	Description
name	true	Name of the notification rule.
actionType	true	Type of the action that notification rule will have. This parameter should be one of create-alert, acknowledged-alert, closed-alert, assigned-alert, add-note, schedule-start, schedule-end and incoming-call-routing.
criteria	false	Defines the conditions that will be checked before applying notification rule and type of the operations that will be applied on conditions. Default value is matching all notification rules. You can refer here for more about the field definition.
notificationTime	*true ()**	List of Time Periods that notification for schedule start/end will be sent. This parameter should be one of just-before, 15-minutes-ago, 1-hour-ago and 1-day-ago
timeRestriction	false	Time interval that notification rule will work. It can be just one restriction which will be applied all days, or list of restrictions will be applied to the specified days. You may refer here for more about the parameter definition.
schedules	false	This field is valid for Schedule Start/End rules. It can be list of schedules that notification rule will be applied when on call of that schedule starts/ends. This field shall only be populated with the specified users' schedules. You refer here for schedule objects.
order	false	The order of the notification rule within the notification rules with the same action type. `order` value is actually the index of the notification rule whose minimum value is 0 and whose maximum value is n-1 (number of notification rules with the same action type is n)
steps	false	List of steps that will be added to notification rule. For further details of `step` object, you can refer here
repeat	false	The amount of time in minutes that notification steps will be repeatedly apply. You may refer here for further information of this parameter. You may also check Create and manage notification preferences for detailed information about repeating
enabled	true	If notification rule will be enabled or not when it is created

🚧
If actionType is scheduleStart or scheduleEnd, notificationTime is mandatory

Sample Requests:

curl -X POST 'https://api.opsgenie.com/v2/users/4b26961a-a837-49d2-a1fe-0973013e3c3b/notification-rules/'
    --header 'Authorization: GenieKey 50b71849-6b09-46d8-bd7b-046b9d942eb4'
    --header 'Content-Type: application/json'
    --data
'{
    "name": "Test Notification Rule",
    "actionType": "schedule-start",
    "enabled" : true,
    "criteria" : {
        "type" : "match-all"
    },
    "order": 1,
    "notificationTime" : ["1-hour-ago"],
    "schedules" : [
        {
          "name" : "test_schedule",
          "type" : "schedule"
        }
    ],
    "repeat" : {
        "loopAfter" : 2
    },
    "timeRestriction" : {
        "type" : "time-of-day",
        "restriction" : {
            "startHour": 3,
            "startMin" : 15,
            "endHour" : 5,
            "endMin" : 30
    }
}'

curl -X POST 'https://api.opsgenie.com/v2/users/[email protected]/notification-rules/'
    --header 'Authorization: GenieKey 50b71849-6b09-46d8-bd7b-046b9d942eb4'
    --header 'Content-Type: application/json'
    --data
'{
    "name": "Create Alert Notification with step",
    "actionType": "create-alert",
    "enabled" : true,
    "criteria" : {
    	"type" : "match-all"
    },
    "order": 1,
    "repeat" : {
    	"loopAfter" : 2
    },
    "timeRestriction" : {
        "type" : "time-of-day",
        "restriction" : {
            "startHour": 3,
            "startMin" : 15,
            "endHour" : 5,
            "endMin" : 30
        }
    },
    "steps" : [
        {
            "contact": {
                "method": "email",
                "to": "[email protected]"
            },
            "sendAfter": {
                "timeAmount": 1
            },
            "enabled" : true
        }
    ]
}'

Response:

{
    "data": {
        "id": "e3face00-e378-4eb1-8141-cd21103d1814",
        "name": "Create Alert Notification with step",
        "actionType": "create-alert",
        "order": 3,
        "enabled": true
    },
    "took": 0.828,
    "requestId": "209ecfca-a25d-4a19-80c1-1f6d26fa95e9"
}

Get Notification Rule

HTTP Method	URL
GET	https://api.opsgenie.com/v2/users/:userIdentifier/notification-rules/:ruleId

In-Line Parameters

Referred Name	Description
userIdentifier	Identifier of the user for this notification rule. You should provide either id or username of the user.
ruleId	Id of the notification rule

Sample Request:

curl -X GET 'https://api.opsgenie.com/v2/users/[email protected]/notification-rules/6250e423-fd5e-451c-8573-a20c61fb9872'
    --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1afdf565c889'

Response:

{
    "data": {
        "id": "6250e423-fd5e-451c-8573-a20c61fb9872",
        "name": "Test Notification Rule",
        "actionType": "schedule-start",
        "notificationTime": ["1-hour-ago"],
        "order": 1,
        "timeRestriction": {
            "type": "time-of-day",
            "restriction": {
                "startHour": 3,
                "endHour": 5,
                "startMin": 15,
                "endMin": 30
            }
        },
        "steps": [],
        "schedules": [
            {
                "id": "af072e63-5925-4609-b7de-d983ad8ce9c1",
                "type": "schedule",
                "name": "test_schedule"
            }
        ],
        "enabled": true
    },
    "took": 0.14,
    "requestId": "a1f871a0-65e0-4a60-81ed-a5102a94617b"
}

Update Notification Rule (Partial)

Update notification rule request is a write request. If the integration of the API key configured as read-only, the request will not be accepted. For more information, you can refer to API Access Management

HTTP Method	URL
PATCH	https://api.opsgenie.com/v2/users/:userIdentifier/notification-rules/:ruleId

In-Line Parameters

Referred Name	Description
userIdentifier	Identifier of the user for this notification rule. You should provide either id or username of the user
ruleId	Id of the notification rule.

JSON Body Fields

Field	Mandatory	Description
name	false	Name of the notification rule
criteria	false	Defines the conditions that will be checked before applying notification rule and type of the operations that will be applied on conditions. Default value is matching all notification rules. You can refer here for more about the field definition.
notificationTime	true*	List of Time Periods that notification for schedule start/end will be sent. This parameter should be one of just-before, 15-minutes-ago, 1-hour-ago and 1-day-ago
timeRestriction	false	Time interval that notification rule will work. It can be just one restriction which will be applied all days, or list of restrictions will be applied to the specified days. You may refer here for more about the parameter definition.
schedules	false	This field is valid for Schedule Start/End rules. It can be list of schedules that notification rule will be applied when on call of that schedule starts/ends. This field shall only be populated with the specified users' schedules. You refer here for schedule objects.
steps	false	List of steps that will be added to notification rule. For further details of `step` object, you can refer here
repeat	false	The amount of time in minutes that notification steps will be repeatedly apply. You may refer here for further information of this parameter. You may also check Create and manage notification preferences for detailed information about repeating
order	false	The order of the notification rule within the notification rules with the same action type. `order` value is actually the index of the notification rule whose minimum value is 0 and whose maximum value is n-1 (number of notification rules with the same action type is n)
enabled	false	If notification rule will be enabled or not when it is created

🚧
If actionType is scheduleStart or scheduleEnd, notificationTime is mandatory

Sample Request:

curl -X PATCH 'https://api.opsgenie.com/v2/users/[email protected]/notification-rules/6250e423-fd5e-451c-8573-a20c61fb9872
    --header 'Authorization: GenieKey 50b71849-6b09-46d8-bd7b-046b9d942eb4'
    --header 'Content-Type: application/json'
    --data
'{
    "name": "Updated preference",
    "notificationTime": ["just-before", "15-minutes-ago" , "1-hour-ago"],
    "schedules" : [
        {
            "name" : "schedule_test",
            "type" : "schedule"
        }
    ],
    "timeRestriction" : {
        "type" : "weekday-and-time-of-day",
    "restrictions" : [
        {
            "startDay" : "monday",
            "endDay" : "friday",
            "startHour" : 13,
            "startMin" : 0,
            "endHour" : 18,
            "endMin" : 0
        }
    ]
}'

Response:

{
    "data": {
        "id": "6250e423-fd5e-451c-8573-a20c61fb9872",
        "name": "Updated preference",
        "actionType": "schedule-start",
        "order": 1,
        "enabled": true
    },
    "took": 0.409,
    "requestId": "f55ce8ff-ac0a-41d6-8fe0-53c937709b0c"
}

Delete Notification Rule

Delete notification rule request is a write request. If the integration of the API key configured as read-only, the request will not be accepted. For more information, you can refer to API Access Management

HTTP Method	URL
DELETE	https://api.opsgenie.com/v2/users/:userIdentifier/notification-rules/:ruleId

In-Line Parameters

Referred Name	Description
userIdentifier	Identifier of the user for this notification rule. You should provide either id or username of the user
ruleId	Id of the notification rule.

Sample Request:

curl -X DELETE 'https://api.opsgenie.com/v2/users/[email protected]/notification-rules/6250e423-fd5e-451c-8573-a20c61fb9872'
    --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1afdf565c889'

Response:

{
    "result": "Deleted",
    "took": 0.257,
    "requestId": "88a7b84c-67f2-4671-9034-1e02a8ebf772"
}

List Notification Rule

HTTP Method	URL
GET	https://api.opsgenie.com/v2/users/:userIdentifier/notification-rules

In-Line Parameters

Referred Name	Description
userIdentifier	Identifier of the user for this notification rule. You should provide either id or username of the user

Sample Request:

curl -X GET 'https://api.opsgenie.com/v2/users/af072e63-5925-4609-b7de-d983ad8ce9c1/notification-rules/6250e423-fd5e-451c-8573-a20c61fb9872'
    --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1afdf565c889'

Response:

{
    "data": [
        {
            "id": "af0bf74f-dd6f-469d-a2e2-e69d1f474c6a",
            "name": "New Alert",
            "actionType": "create-alert",
            "order": 1,
            "enabled": true
        },
        {
            "id": "487622ab-b4bc-4aed-a043-640ffeb52393",
            "name": "Acknowledged Alert",
            "actionType": "acknowledged-alert",
            "order": 2,
            "enabled": true
        },
        {
            "id": "610d9217-5557-4773-977b-e556639f36e6",
            "name": "Closed Alert",
            "actionType": "closed-alert",
            "order": 3,
            "enabled": true
        },
        {
            "id": "34622362-2cb0-4bb5-b4f6-329aded25801",
            "name": "Schedule Start",
            "actionType": "schedule-start",
            "order": 4,
            "enabled": true
        },
        {
            "id": "ae4bba81-fc97-4a39-a191-f6de0077d9be",
            "name": "Assigned Alert",
            "actionType": "assigned-alert",
            "order": 6,
            "enabled": true
        },
        {
            "id": "904b3711-04df-453b-83d5-b432e44b94ec",
            "name": "Add Note",
            "actionType": "add-note",
            "order": 7,
            "enabled": true
        },
        {
            "id": "7f395466-25a6-4e07-9e57-99e6d0d8e44c",
            "name": "Incoming Call Routing",
            "actionType": "incoming-call-routing",
            "order": 8,
            "enabled": true
        }
    ],
    "took": 0.117,
    "requestId": "05c9f1a3-611b-4741-8615-fd9e237539d4"
}

Enable Notification Rule

Enable notification rule request is a write request. If the integration of the API key configured as read-only, the request will not be accepted. For more information, you can refer to API Access Management

HTTP Method	URL
POST	https://api.opsgenie.com/v2/users/:userIdentifier/notification-rules/:ruleId/enable

In-Line Parameters

Referred Name	Description
userIdentifier	Identifier of the user for this notification rule. You should provide either id or username of the user
ruleId	Id of the notification rule.

Sample Request:

curl -X POST 'https://api.opsgenie.com/v2/users/af072e63-5925-4609-b7de-d983ad8ce9c1/notification-rules/6250e423-fd5e-451c-8573-a20c61fb9872/enable'
    --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1afdf565c889'

Response:

{
    "result": "Enabled",
    "data": {
        "id": "a8e54bca-8f3f-45f9-b6a0-65487a81220c",
    },
    "took": 0.906,
    requestId": "3e312a96-b750-40c2-a845-924c63f0d035"
}

Disable Notification Rule

Disable notification rule request is a write request. If the integration of the API key configured as read-only, the request will not be accepted. For more information, you can refer to API Access Management

HTTP Method	URL
POST	https://api.opsgenie.com/v2/users/:userIdentifier/notification-rules/:ruleId/disable

In-Line Parameters

Referred Name	Description
userIdentifier	Identifier of the user for this notification rule. You should provide either `id` or `username` of the user.
ruleId	Id of the notification rule.

Sample Request:

curl -X POST 'https://api.opsgenie.com/v2/users/[email protected]/notification-rules/6250e423-fd5e-451c-8573-a20c61fb9872/disable'
    --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1afdf565c889'

Response:

{
    "result": "Disabled",
    "data": {
        "id": "a8e54bca-8f3f-45f9-b6a0-65487a81220c",
    },
    "took": 0.906,
    "requestId": "3e312a96-b750-40c2-a845-924c63f0d035"
}

Copy Notification Rules to Other Users

Copy notification rules to other users request is a write request. If the integration of the API key configured as read-only, the request will not be accepted. For more information, you can refer to API Access Management

HTTP Method	URL
POST, PUT, PATCH	https://api.opsgenie.com/v2/users/:userIdentifier/notification-rules/copy-to

In-Line Parameters

Referred Name	Description
userIdentifier	Identifier of the user that the notification rules belong to originally. You should provide either `id` or `username` of the user.

JSON Body Fields

Field	Mandatory	Description
toUsers	true	Specify a list of the users which you want to copy the rules to. You can use the username of a user, or to copy to all users, "all".
ruleTypes	true	Specify a list of the action types you want to copy the rules of. It can contain "New Alert", "Acknowledged Alert" or for all types of notification rules, "all". The total list of valid types are: all, acknowledged-alert, renotified-alert, closed-alert, schedule-start, assigned-alert, add-note, new-alert

Sample Requests:

curl -X PATCH 'https://api.opsgenie.com/v2/users/[email protected]/notification-rules/copy-to
    --header 'Authorization: GenieKey 50b71849-6b09-46d8-bd7b-046b9d942eb4'
    --header 'Content-Type: application/json'
    --data
'{
    "toUsers": ["username1", "username2" , "username3"],
    "ruleTypes": ["new-alert", "schedule-start"]
    
}'

Response:

{
    "result": "Started copying notification rules",
    "took": 0.583,
    "requestId": "f2ec7f39-4bc6-4e39-9d22-0d89882c5e73"
}

Fields of Step Object

Field	Mandatory	Description
contact	true	Defines the contact that notification will be sent to. `contact` parameter takes a contact object which is explained here with details.
sendAfter	true*	Minute time period notification will be sent after. It should be given as an object which has a `timeAmount` field that takes amount as minutes
enabled	true	This parameter is used to specify if given step will be enabled or not when it is created

🚧
sendAfter is only mandatory for new alert and assigned alert notification rules

step Example:

{
    "contact": {
        "method": "email",
        "to": "[email protected]"
    },
    "sendAfter": {
        "timeAmount": 1
    },
    "enabled" : true
}

Fields of Contact Object

Parameter	Mandatory	Description
method	true	Contact method of user and should be one of email, sms, voice or mobile.
to	true	Address of given method

contact field example:

{
    "contact": {
        "method": "email",
        "to": "[email protected]"
    }
}

Criteria Fields

Defines the conditions that will be checked before applying notification rules and type of the operations that will be applied on these conditions

JSON Body Fields

Field	Mandatory	Description
type	true	Type of the operation will be applied on conditions. Should be one of match-all, match-any-condition or match-all-conditions
conditions	true*	List of conditions will be checked before applying team routing rule

🚧
If operation type is match-all, conditions field is not necessary/mandatory.

Fields of Conditions Object

Field	Mandatory	Description
field	true	Specifies which alert field will be used in condition. Possible values are message, alias, description, source, entity, tags, actions, extra-properties, recipients, teams or priority
key	false	If `field` is set as extra-properties, `key` could be used for key-value pair
not	false	Indicates behaviour of the given operation. Default value is false
operation	true	It is the operation that will be executed for the given field and key. Possible operations are matches, contains, starts-with, ends-with, equals, contains-key, contains-value, greater-than, less-than, is-empty and equals-ignore-whitespace. Available operations changes according to the fields type: String Operations: `contains`, `equals`, `starts-with`, `ends-with`, `matches`, `is-empty`, `equals-ignore-whitespace` List Operations: `contains`, `is-empty` Map Operations: `contains`, `contains-key`, `contains-value`, `is-empty` Number Operations: `matches`, `equals`, `greater-than`, `less-than` * Boolean Operations: `equals`
expectedValue	false	User defined value that will be compared with alert field according to the operation. Default value is empty string
order	false	Order of the condition in conditions list

criteria field example:

{
    "criteria": {
        "type": "match-all"
    }
}

{
    "criteria": {
        "type": "match-any-condition",
        "conditions": [
            {
                "field": "message",
                "not": false,
                "operation": "contains",
                "expectedValue": "expected1"
            },
            {
                "field": "alias",
                "not": true,
                "operation": "starts-with",
                "expectedValue": "expected2"
            },
            {
                "field": "extra-properties",
                "key": "expectedKey",
                "not": true,
                "operation": "starts-with",
                "expectedValue": "expected3"
            }
        ]
    }
}

Time Restriction Fields

Used to limit notification rules to certain day and time of the week, using multiple start and end times for each day of the week.

Day Based Restriction

If the time restrictions will be configured as day based, this parameter should be used. timeRestriction parameter for daily restrictions should have the following format:

Field	Mandatory	Description
type	true	This parameter should be set time-of-day
restriction	true	It is a restriction object which is described below. In this case `startDay`/`endDay` fields are not supported

Fields of Restriction Object

Field	Mandatory	Description
startHour	true	Value of the hour that frame will start
startMin	true	Value of the minute that frame will start.
endHour	true	Value of the hour that frame will end
endMin	true	Value of the minute that frame will end.

restriction field example:

{
    "timeRestriction": {
        "type" : "time-of-day",
        "restriction" :
        {
            "startHour" : 8,
            "startMin" : 0,
            "endHour" : 18,
            "endMin" : 30
        }
    }
}

Week Based Restrictions

If the time restrictions will be configured as week based, this parameter should be used. timeRestriction parameter for weekly restrictions should have the following format:

Parameter	Mandatory	Description
type	true	This parameter should be set weekday-and-time-of-day
restrictions	true	It is a list of restriction objects which are described below

Fields of Restrictions Object

Field	Mandatory	Description
startDay	true	Name of day which time frame will start. May be one of monday, tuesday, wednesday, thursday, friday, saturday, sunday. Only used if type of `restrictions` is given weekday-and-time-of-day
startHour	true	Value of the hour that frame will start
startMin	true	Value of the minute that frame will start
endDay	true	Name of day which time frame will end. May be one of monday, tuesday, wednesday, thursday, friday, saturday, sunday. Only used if type of `restrictions` is given weekday-and-time-of-day
endHour	true	Value of the hour that frame will end
endMin	true	Value of the minute that frame will end.

restrictions field example

{
    "timeRestriction": {
        "type" : "weekday-and-time-of-day",
        "restrictions" : [
            {
                "startDay" : "monday",
                "startHour" : 8,
                "startMin" : 0,
                "endDay" : "tuesday",
                "endHour" : 18,
                "endMin" : 30
            },
            {
                "startDay" : "wednesday",
                "startHour" : 8,
                "startMin" : 0,
                "endDay" : "thursday",
                "endHour" : 18,
                "endMin" : 30
            }
        ]
    }
}

Fields of Schedule Object

Field	Mandatory	Description
type	true	This parameter is mandatory and should be set as schedule
name	false	Name of the schedule
id	false	Id of the schedule

🚧
One of the id or name of the schedule should be provided

schedule object example:

{
    "type" : "schedule"
    "name" : "test_schedule",
}

Fields of Repeat Object

Field	Mandatory	Description
loopAfter	true	This parameter is amount in minutes that notification steps will be repeatedly apply. It can not be less than 0.
enabled	false	Determine whether loopAfter is enabled or not. If it is set to false, repeating will be disabled.

repeat field example:

{
    "repeat" : {
        "loopAfter" : 2,
        "enabled" : true
    }
}