Note: This page has not yet been converted to the new developer portal format. Please use Swagger to test this API.
Calendar Events
GET /scheduling/{organizationId}/calendarEvents
Description
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:
1 A contact or group
was added to a staff layer.
2 A contact or group
was added to a shift override.
3 A contact was set as
a replacement to an unavailable contact in 1 or 2 above.
Return type
Calendar Event
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:
When a group is assigned to a staff layer, then assignments will show one record
for each contact in the group. It will also add the group ID so that you can see that the contact was
assigned to that layer because of the group. The following is an example:
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:
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:
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 unavailable
from 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:
URL Parameters
| Name | Required? | Data Type | Options | Description |
|---|---|---|---|---|
organizationId | y | long | The ID of the organization. |
Header
| Name | Required? | Data Type | Options | Description |
|---|---|---|---|---|
Authorization | y | string | Basic base64_encode(username:password) Ex: If username = myusername & password = mypassword Then "Authorization" value will be: Basic base64_encode(myusername:mypassword) = Basic bXl1c2VybmFtZTpteXBhc3N3b3Jk |
Request Parameters
| Name | Required? | Data Type | Options | Description |
|---|---|---|---|---|
include | n | string | Ex: ?include=contact,group,calendar,shiftSchedule,staffSchedule | What data you want to be included in the response. Includes the details of the specified resource(s) that are referenced in the calendar event objects. This can be none or any combination of the following resources: contact, group, calendar, shiftSchedule, staffSchedule, shiftSubstitution, staffSubstitution. |
fields[resource] | n | string | Ex: fields[calendar]=name&fields[shiftSchedule]=name&field[ccontact]=paths This includes the name of the calendars, the name of the shifts, and paths for the contacts in the response. | Add only specific fields of the "included" resource in the response. |
filter | n | string | Ex: filter[calendarId]=1234567890,7788990066 | The filter may be used to specify filter criteria for the request. Filters are specified in the format of filter[fieldName], where fieldName is any field supported by this resource. Multiple filter criteria will result in AND conditions, with the exception of multiple filters on the same field, in which case the criteria will be treated as an OR condition. |
calendarId | n | Long | Ex: calendarId=1234567890,7788990066 | None or many calendar IDs to filter by. NOTE: "filter" param can also be used to filter the same. |
shiftScheduled | n | Long | Ex: shiftScheduleId=1234567890,7788990066 | None or many shift IDs to filter by. |
start | n | DateTime (UTC) | Ex: start=2019-11-19T00:00:00-05:00&end=2019-11-23T00:00:00-05:00 To retrieve the events that happen between 2019-11-19 12:00 AM EST and 2019-11-23 12:00 AM EST | Beginning of the interval to search for. |
end | n | DateTime (UTC) | Ex: start=2019-11-19T00:00:00-05:00&end=2019-11-23T00:00:00-05:00 To retrieve the events that happen between 2019-11-19 12:00 AM EST and 2019-11-23 12:00 AM EST | End of the interval to search for. |
days | n | Integer | Ex: start=2019-11-19T00:00:00-05:00&days=7 To retrieve the events that happen from 2019-11-19 12:00 AM EST until the next 7 days | The number of days to search for. |
Example Request and Response
| Code | Response |
|---|---|
200 | { "data": [ { "id": "010a810001394f-5dd376d0-5dd4c850", "type": "calendarEvent", "assignments": [ { "contactId": 884020233694504, "staffLayerId": 293024143866482 } ], "calendarId": 293024143839397, "end": "2019-11-20T00:00:00-05:00", "organizationId": 888409690212737, "shiftScheduleId": 293024143849807, "start": "2019-11-19T00:00:00-05:00" }, { "id": "010a810001394f-5dd4c850-5dd619d0", "type": "calendarEvent", "assignments": [ |
{ "contactId": 884020233694504, "staffLayerId": 293024143866482 } ], "calendarId": 293024143839397, "end": "2019-11-21T00:00:00-05:00", "organizationId": 888409690212737, "shiftScheduleId": 293024143849807, "start": "2019-11-20T00:00:00-05:00" }, { "id": "010a810001394f-5dd619d0-5dd76b50", "type": "calendarEvent", "assignments": [ { "contactId": 884020233694504, "staffLayerId": 293024143866482 } ], "calendarId": 293024143839397, "end": "2019-11-22T00:00:00-05:00", "organizationId": 888409690212737, "shiftScheduleId": 293024143849807, "start": "2019-11-21T00:00:00-05:00" } ], "included": [ { "id": 293024143839397, "type": "calendar", "name": "Events Test" }, { "id": 293024143849807, "type": "shiftSchedule", "name": "My shift" }, { "id": 293024143866482, "type": "staffSchedule", "name": "L1" }, { "id": 884020233694504, "type": "contact", "firstName": "Contact", "lastName": "One" } ] } |