List Calendar Events

The Calendar Events API is designed to help clients find who are on-call for a specified period of time or an instant.
What are events? An event is considered a moment in time when a contact and/or group will be assigned to a Calendar and Shift combination.
What is an assignment? When a contact and/or group is assigned to a specific moment in time, if a notification happens, that contact and/or contacts in the group will be notified.

When does an assignment happen? Assignments can happen for three reasons:

• A contact or group was added to a staff layer.
• A contact or group was added to a shift override.
• A contact was set as a replacement to an unavailable contact in 1 or 2 above.

Return type

Calendar Event

{
  "id": "08e1b060000001-672bb5a8-672d0728",
  "type": "calendarEvent",
  "assignments": [],
  "calendarId": 2481052283043883,
  "end": "2024-11-08T00:00:00+05:30",
  "organizationId": 1536984111644674,
  "shiftScheduleId": 2499947454791681,
  "start": "2024-11-07T00:00:00+05:30"
}

Assignments

Inside the assignments attribute, you will get an array of all the contacts assigned to the event. Multiple contacts can be assigned depending on each situation. The simplest format for an assignment is the following, which happens when a contact is directly assigned to a staff layer:

{
  "contactId": 444206992589469,
  "groupId": 998776788790,
  "staffLayerId": 281517890390,
},
{
  "contactId": 444206992591912,
  "groupId": 9987767884547,
  "staffLayerId": 281517890908,
}

In the previous example, two contacts (444206992589469 and 444206992591912) were assigned to the staff layer because they were added to a group (281616710631446), which was added to the staff layer.
When a contact or group is assigned to a shift using the shift override functionality, then they do not get a staffLayerId. Instead, they have a shiftSubstitutionId.
Besides that, everything else works the same way. The following is an example:

{
  "contactId": 444206992591913,
  "shiftSubstitutionId": 28151789039045636, //No Staff Layer, shiftSubstitutionId instead
},
{
  "contactId": 444206992591913, // This contact was assigned because he/she belongs to the group
  "groupId": 576328739230323,  // This group was assigned to this shift override  
  "shiftSubstitutionId": 28151789039045636, //No Staff Layer, shiftSubstitutionId instead
}

If a contact is set to unavailable for some amount of time, its replacement (if any) will show as an assignment.
It will also have a replacements attribute, which lists all the periods of time in which that contact is replacing someone.
Inside each replacement, you will also see a replacedContactId that indicates what contact is being replaced and a staffSubstitutionId, which is the ID of the substitution that the replacement refers to. Here is an example:

{
  "contactId": 444206992591913,  // This contact is replacing someone
  "replacements": [  // Can reaplce multiple times in a shift
    {
      "replacedContactId": 444206992591912,  // This contact is being reaplced
      "replacementPeriod": {
        "from": "2024-11-08T00:00:00+05:30",  // Replacement period start
        "to": "2024-12-08T00:00:00+05:30"  // and end time
      },
      "staffSubstitutionId": 28151789039043336  // Substitution Id
    }
  ],
  "staffLayerId": 281517890390321  // This replacement is in this staff layer
}

If a contact is unavailable for a period of time contained in the shift time (for example, the shift goes from 9:00am-5:00pm and the contact is unavailablefrom 12:00pm-1:00pm), then the contact will still be assigned to the shift, but it will have an attribute unavailabilities,
which is an array for which all the periods the contact is unavailable. Each unavailability will also include the ID of the contact that is replacing the unavailable contact (if present) and staffSubstitutionId, which is the ID of the substitution that the unavailability refers to. The following is an example:

{
  "contactId": 444206992591913,  // Contact that is unavailable
  "staffLayerId": 281517890390321,  // Staff layer that this contact is assigned to
  "unavailabilities": [  // Can be unavailable multiple times in a shift
    {
      "period": {
         "from": "2024-11-08T00:00:00+05:30",  // start
         "to": "2024-12-08T00:00:00+05:30"  // and end time
      },
      "replacedById": 444206992591912,  // Contact Id replacing this contact
      "staffSubstitutionId": 28151789039043336  // Substitution Id
    }
  ]
}

Request Parameters

Example Request

curl -X GET 'https://api-qal.everbridge.net/rest/scheduling/888409690212737/
calendarEvents?include=contact,calendar,shiftSchedule,staffSchedule&fields[calendar]=name&fields[shiftSchedule]= name&fields[staffSchedule]=name&start=2019-11-19T00:00:00-05:00&days=3&filter[calendarId]=293024143839397'
H'Authorization: Basic cGF1bG9taS5tYWhpZGhhcmIhOlBhdWx='