Who is On Call 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

📘
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.

📘
All requests of Who Is On Call API work under Schedule domain. It means that; If you are using apiKey belongs to a team integration, that team must allowed to access given schedule. Otherwise, we would respond with 403 - Forbidden (Unauthorized) with 40301 internal code Response

Get On Calls

Get on-call request is used to retrieve current on-call participants of a specific schedule. It takes the following parameters:

HTTP Method	URL
GET	https://api.opsgenie.com/v2/schedules/:scheduleIdentifier/on-calls

In-Line Parameters

Referred Name	Description
scheduleIdentifier	Identifier of the schedule

Query Parameters

Parameter	Mandatory	Description
scheduleIdentifierType	false	Type of the schedule identifier that is provided as an in-line parameter. Possible values are id and name. Default value is id
flat	false	When enabled, retrieves user names of all on call participants. Default value is false
date	false	Starting date of the timeline that will be provided in format as (yyyy-MM-dd'T'HH:mm:ssZ) (e.g. 2017-01-15T08:00:00+02:00). Default date is the moment of the time that request is received

🚧
You should escape the plus sign in your url with '%2B', if you are using console for curl requests

Sample Request

curl -X GET  'https://api.opsgenie.com/v2/schedules/ScheduleName/on-calls?scheduleIdentifierType=name&flat=true'
    --header 'Authorization: GenieKey eb24alp-faa2-4ba2-a551q-1alpf565c889'

Response (with flat = false ):

{
    "data": {
        "_parent": {
            "id": "d875alp4-9b4e-4219-alp3-0c26936d18de",
            "name": "ScheduleName",
            "enabled": true
        },
        "onCallParticipants": [
            {
                "id": "c569c016-alpc-4e20-8a28-bd5dc33b798e",
                "name": "TeamName",
                "type": "team"
            },
            {
                "id": "15445alp-e46c-446f-9236-7ad89ad1a4f7",
                "name": "TeamName_escalation",
                "type": "escalation",
                "onCallParticipants": [
                    {
                        "id": "e55700e1-ff76-4cd0-a6e8-e1a982423alp",
                        "name": "TeamName_schedule",
                        "type": "schedule",
                        "escalationTime": 0,
                        "notifyType": "default"
                    },
                    {
                        "id": "e55700e1-ff76-4cd0-a6e8-e1a982423alp",
                        "name": "TeamName_schedule",
                        "type": "schedule",
                        "escalationTime": 5,
                        "notifyType": "next"
                    },
                    {
                        "id": "c569c016-alpc-4e20-8a28-bd5dc33b798e",
                        "name": "TeamName",
                        "type": "team",
                        "onCallParticipants": [
                            {
                                "id": "balp7783-a9f1-40e3-940c-ffde45656054",
                                "name": "[email protected]",
                                "type": "user"
                            },
                            {
                                "id": "4falpb2e-348d-4b7c-b71b-149efb8361e4",
                                "name": "[email protected]",
                                "type": "user"
                            }
                        ],
                        "escalationTime": 10,
                        "notifyType": "all"
                    }
                ]
            }
        ]
    },
    "took": 0.305,
    "requestId": "e28ce37b-d81c-4b1d-abb8-0c371d8alp5f"
}

Response (with flat = true ):

{
    "data": {
        "_parent": {
            "id": "d875alp4-9b4e-4219-a803-0c26936d18de",
            "name": "ScheduleName",
            "enabled": true
        },
        "onCallRecipients": [
            "[email protected]"
        ]
    },
    "took": 0.101,
    "requestId": "7f0alpde-3c67-455f-97ec-24754432d413"
}

🚧
notifyType *is the escalation rule's notify type for schedules. Possible values are:

default: *On-call users of the schedule.

next: *Next user in the schedule.

previous: *Previous user in the schedule.

🚧
forwardedFrom returns information of forwarding user if there is a forwarding in our schedule. Example can be found down below

List On Calls

❗️
DEPRECATED
List On-Calls endpoint is deprecated since 31th August 2018.

List who is on call request is used to retrieve current on-call participants of all schedules. It takes the following parameters:

HTTP Method	URL
GET	https://api.opsgenie.com/v2/schedules/on-calls

Query Parameters

Referred Name	Description
flat	When enabled, retrieves user names of all on call participants. Default value is false
date	Starting date of the timeline that will be provided in format as (yyyy-MM-dd'T'HH:mm:ssZ) (e.g. 2017-01-15T08:00:00+02:00). Default date is the moment of the time that request is received

🚧
You should escape the plus sign in your url with '%2B', if you are using console for curl requests

Sample Request

curl -X GET 'https://api.opsgenie.com/v2/schedules/on-calls'
    --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1alpf565c889'

Response (with flat = false ):

{
    "data": [
        {
            "_parent": {
                "id": "d875alp4-9b4e-4219-alp3-0c26936d18de",
                "name": "ScheduleName",
                "enabled": true
            },
            "onCallParticipants": [
                {
                    "id": "balp7783-a9f1-40e3-940c-ffde45656054",
                    "name": "[email protected]",
                    "type": "user",
                    "forwardedFrom": {
                        "id": "a9514028-2bca-4510-a51f-4b65alp33a56",
                        "name": "[email protected]",
                        "type": "user"
                    }
                },
                {
                    "id": "15445alp-e46c-446f-9236-7ad89ad1a4f7",
                    "name": "TeamName_escalation",
                    "type": "escalation",
                    "onCallParticipants": [
                        {
                            "id": "e55700e1-ff76-4cd0-a6e8-e1a982423alp",
                            "name": "TeamName_schedule",
                            "type": "schedule",
                            "escalationTime": 0,
                            "notifyType": "default"
                        },
                        {
                            "id": "e55700e1-ff76-4cd0-a6e8-e1a982423alp",
                            "name": "TeamName_schedule",
                            "type": "schedule",
                            "escalationTime": 5,
                            "notifyType": "next"
                        },
                        {
                            "id": "c569c016-alpc-4e20-8a28-bd5dc33b798e",
                            "name": "TeamName",
                            "type": "team",
                            "onCallParticipants": [
                                {
                                    "id": "balp7783-a9f1-40e3-940c-ffde45656054",
                                    "name": "[email protected]",
                                    "type": "user"
                                },
                                {
                                    "id": "4falpb2e-348d-4b7c-b71b-149efb8361e4",
                                    "name": "[email protected]",
                                    "type": "user"
                                }
                            ],
                            "escalationTime": 10,
                            "notifyType": "all"
                        }
                    ]
                }
            ]
        },
        {
            "_parent": {
                "id": "e55700e1-ff76-4cd0-a6e8-e1a982423alp"",
                "name": "TeamName_schedule",
                "enabled": true
            },
            "onCallParticipants": [
                {
                    "id": "4falpb2e-348d-4b7c-b71b-149efb8361e4",
                    "name": "[email protected]",
                    "type": "user"
                }
            ]
        }
    ],
    "took": 0.154,
    "requestId": "9819alp8-7922-41f8-b350-9dc219ffa53b"
}

Response (with flat = true ):

{
    "data": [
        {
            "_parent": {
                "id": "d875alp4-9b4e-4219-alp3-0c26936d18de",
                "name": "ScheduleName",
                "enabled": true
            },
            "onCallRecipients": [
                "[email protected]",
                "[email protected]"
            ]
        },
        {
            "_parent": {
                "id": "e55700e1-ff76-4cd0-a6e8-e1a982423alp"",
                "name": "TeamName_schedule",
                "enabled": true
            },
            "onCallRecipients": [
                "[email protected]"
            ]
        }
    ],
    "took": 0.039,
    "requestId": "8f7345f2-63e4-414b-b06f-eb39396575ef"
}

Get Next On Calls

Get next on-call request is used to retrieve next on-call participants of a specific schedule. It takes the following parameters:

HTTP Method	URL
GET	https://api.opsgenie.com/v2/schedules/:scheduleIdentifier/next-on-calls

In-Line Parameters

Referred Name	Description
scheduleIdentifier	Identifier of the schedule

Query Parameters

Parameter	Mandatory	Description
scheduleIdentifierType	false	Type of the schedule identifier that is provided as an in-line parameter. Possible values are id and name . Default value is id
flat	false	When enabled, retrieves user names of all next on call participants. Default value is false
date	false	Starting date of the timeline that will be provided in format as (yyyy-MM-dd'T'HH:mm:ssZ) (e.g. 2017-01-15T08:00:00+02:00). Default date is the moment of the time that request is received

🚧
You should escape the plus sign in your url with '%2B', if you are using console for curl requests

Sample Request

curl -X GET  'https://api.opsgenie.com/v2/schedules/ScheduleName/next-on-calls?scheduleIdentifierType=name'
    --header 'Authorization: GenieKey eb24alp-faa2-4ba2-a551q-1alpf565c889'

Response (with flat = false ):

{
    "data": {
        "_parent": {
            "id": "ef6282c2-6fd4-405b-ae7b-60fc73906272",
            "name": "ScheduleName",
            "enabled": true
        },
        "nextOnCallRecipients": [
            {
                "id": "1f281991-bca3-4ae2-balp-b02e94d10953",
                "name": "[email protected]",
                "type": "user",
                "forwardedFrom": {
                    "id": "a9514028-2bca-4510-a51f-4b65f2c33a56",
                    "name": "[email protected]",
                    "type": "user"
                }
            }
        ],
        "exactNextOnCallRecipients": [
            {
                "id": "1f281991-bca3-4ae2-bdea-b02e94d10953",
                "name": "[email protected]",
                "type": "user"
            }
        ]
    },
    "took": 0.039,
    "requestId": "290165e0-ce4d-4e4d-9272-88f6692a55c0"
}

🚧
nextOnCallRecipients field contains next on-call participants in the schedule rotation with more detailed display (including forwarding of these users). On the other hand, exactNextOnCallRecipients contains next on-call recipients (final form) like in the final schedule view. For example, it will be different from nextOnCallRecipients, if there are overrides to the rotation. Other than that, the response format is the same for both fields.

🚧
exactNextOnCallRecipients field calculated for 2 weeks ahead from given date. For example; If we had a 3 week rotation and give start of the first week as date, exactNextOnCallRecipients will return an empty array*

Response (with flat = true ):

{
    "data": {
        "_parent": {
            "id": "d875e654-9b4e-4219-a803-0c26936d18de",
            "name": "ScheduleName",
            "enabled": true
        },
        "exactNextOnCallParticipants": [
            "[email protected]"
        ],
        "nextOnCallParticipants": [
            "[email protected]"
        ]
    },
    "took": 0.146,
    "requestId": "f268ac23-18ad-444d-alpc-6b7e5d999afe"
}

Export On-Call User

Export on call user request is used to export personal on-call timeline of 3 months to a .ics file. It takes the following parameters:

HTTP Method	URL
GET	https://api.opsgenie.com/v2/schedules/on-calls/:identifier.ics

In-Line Parameters

Referred Name	Description
identifier	Identifier of the user, consist of its id or username

Sample Request

curl -X GET 'https://api.opsgenie.com/v2/schedules/on-calls/[email protected]'
    --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1alpf565c889'

Response:

Returns an .ics file with the name of the user

🚧

General Information

📘

📘

Get On Calls

🚧

🚧

🚧

List On Calls

❗️DEPRECATED

🚧

Get Next On Calls

🚧

🚧

🚧

Export On-Call User

❗️
DEPRECATED