Notification Rule API

General Information

Domains


Requests

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 Notification Settings 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 Notification Settings 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/user1@opsgenie.com/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": "user@opsgenie.com"
            },
            "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/user@opsgenie.com/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 Notification Settings 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/user@opsgenie.com/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/user@opsgenie.com/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/user@opsgenie.com/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"
}


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": "user@opsgenie.com"
    },
    "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": "user@opsgenie.com"
    }
}

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 or teams
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
    }
}