Who Is On Call API

General Information


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.
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": "user5@opsgenie.com",
                                "type": "user"
                            },
                            {
                                "id": "4falpb2e-348d-4b7c-b71b-149efb8361e4",
                                "name": "user4@opsgenie.com",
                                "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": [
            "user4@opsgenie.com"
        ]
    },
    "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

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

Parameter Mandatory Description
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/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": "user5@opsgenie.com",
                    "type": "user",
                    "forwardedFrom": {
                        "id": "a9514028-2bca-4510-a51f-4b65alp33a56",
                        "name": "user@opsgenie.com",
                        "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": "user5@opsgenie.com",
                                    "type": "user"
                                },
                                {
                                    "id": "4falpb2e-348d-4b7c-b71b-149efb8361e4",
                                    "name": "user4@opsgenie.com",
                                    "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": "user4@opsgenie.com",
                    "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": [
                "user4@opsgenie.com",
                "user5@opsgenie.com"
            ]
        },
        {
            "_parent": {
                "id": "e55700e1-ff76-4cd0-a6e8-e1a982423alp"",
                "name": "TeamName_schedule",
                "enabled": true
            },
            "onCallRecipients": [
                "user4@opsgenie.com"
            ]
        }
    ],
    "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": "user2@opsgenie.com",
                "type": "user",
                "forwardedFrom": {
                    "id": "a9514028-2bca-4510-a51f-4b65f2c33a56",
                    "name": "user@opsgenie.com",
                    "type": "user"
                }
            }
        ],
        "exactNextOnCallRecipients": [
            {
                "id": "1f281991-bca3-4ae2-bdea-b02e94d10953",
                "name": "user2@opsgenie.com",
                "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": [
            "user2@opsgenie.com"
        ],
        "nextOnCallParticipants": [
            "user2@opsgenie.com"
        ]
    },
    "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 Requests
curl -X GET 'https://api.opsgenie.com/v2/schedules/on-calls/user@opsgenie.com.ics'
    --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1alpf565c889'
Response:

Returns an .ics file with the name of the user