Note: This page has not yet been converted to the new developer portal format. Please use Swagger to test this API.
Substitutions
Substitutions define
exceptions to the schedule, where individual staff or all staff assigned to a shiftSchedule or calendar are
either unavailable or replaced.
Absence of a staffAssignment
indicates the substitution indicates unavailability.
Presence of a staffAssignment,
indicates the substitution indicates a replacement.
Validations
◊ datesApplicable.from
and datesApplicable.to
are required. time.start
and time.end
are optional.
• If an iCal
recurrence is specified and end date is included in the expression, datesApplicable.to
is optional.
– If datesApplicable.to
is configured it will constrain, but not extend the applicable dates.
• if the iCal
recurrence expression indicates an end date of 2017-02-25 and datesApplicable.to is
configured as 2017-02-15, then the recurrence will end on
2017-02-15.
◊ A recurrence
pattern is required.
◊ timeZoneString
is required if calendarId
or shiftScheduleId
is not configured.
◊ calendarId
must be the ID of a valid, active Calendar.
A Staff Substitution defines an exception that can occur or recur over time to
replace or remove a staff member from the schedule.
◊ Applies to a calendar
using the calendarId.
◊ Defines Replacement when
staffAssignment is specified, Unavailability otherwise.
◊ Recurrence may specify
any available recurrence pattern (see below).
◊ Time may optionally
specify a period of time on the configured days for which the substitution applies. This may result in
partial availability for a shift.
Replacement
Unavailable
Substitution Fields
| Parameter | Data Type | Description |
|---|---|---|
calendarId | integer | The ID of the Calendar associated to this resource. |
contactId | integer | The ID of the Contact for which the substitution applies. The unavailable or replaced Contact. |
status | string | Indicates whether the resource is active or deleted. |
recurrence | Recurrence | A valid occurrence Recurrence. See Recurrences. |
staffAssignment | StaffingAssignment | A valid contact staffing assignment. See Staff Assignments. The replacement contact. |
timeZoneString | string | A valid timezone. |
GET /scheduling/{organizationId}/substitutions
Description
Return a list of Scheduling Substitutions within an organization
(Unavailable/Replacement).
Return Type
Substitutions Object
Parameters
| Name | Required? | Data Type | Options | Description |
|---|---|---|---|---|
credentials | y | string | Basic Authorization header. | |
organizationId | y | long | The ID of the Organization that owns this resource. | |
fields | n | string | Any StaffSubstitution field Ex: calendarId, contactId | Fields to be included in the response. Fields[resourceName] may be used to specify fields returned for included documents. When doing so, it is not necessary to also request to include the resource as the include is implied by the fields request. |
include | n | string | "contact", "calendar" | Specifying the includes parameter will result in a compound document response, adding resources to included which have been referenced by resources returned in data. Include may be specified as a comma-delimited list of resource names. |
filter | n | string | Any non transient StaffSubstitution field Ex: filter[calendarId], filter[contactId] | 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. |
sort | n | string | Any non transient StaffSubstitution field Ex: calendarId, contactId | Comma-delimited list of fields to sort by. +/- can precede the field name to indicate direction (ascending/descending) + is the default direction Ex. sort=status,-createdDate sorts by status ascending and createdDate descending |
pageSize | n | integer | default of 10 format - int32 | The number of records per page to be included in the response. |
pageNo | n | integer | default of 1 format - int32 | The page to be returned. |
Example Response
POST /scheduling/{organizationId}/substitutions
Description
Create scheduling substitutions for an organization (Unavailable/Replacement).
Return Type
substituions Object
Parameters
| Name | Required? | Data Type? | Description |
|---|---|---|---|
credentials | y | string | Basic Authorization header. |
organizationId | y | long | The ID of the Organization that owns this resource. |
data | y | httpRequestBody | A substitution object or array of substitution objects to be created. |
Example Request
Example Response
GET /scheduling/{organizationId}/substitutions/{ids}
Description
Retrieve scheduling substitution(s) by ID for an organization
(Unavailable/Replacement).
Return Type
substitutions Object
Parameters:
| Name | Required? | Data Type | Options | Description |
|---|---|---|---|---|
credentials | y | string | Basic Authorization header. | |
organizationId | y | long | The ID of the organization that owns this resource. | |
ids | y | string | The ID or IDs (comma-delimited) of the resources to update. | |
fields | n | string | Any non transient StaffSubstitution field Ex: calendarId, contactId | Fields to be included in the response. Fields[resourceName] may be used to specify fields returned for included documents. When doing so, it is not necessary to also request to include the resource as the include is implied by the fields request. |
include | n | string | "calendar", "contact" | Specifying the includes parameter will result in a compound document response, adding resources to included which have been referenced by resources returned in data. Include may be specified as a comma-delimited list of resource names. |
Example Response
PUT /scheduling/{organizationId}/substitutions/{ids}
Description
Update scheduling substitution(s) by ID for an organization
(Unavailable/Replacement).
Return Type
substitution Object
Parameters
| Name | Required? | Data Type? | Description |
|---|---|---|---|
credentials | y | string | Basic Authorization header. |
organizationId | y | long | The ID of the Organization that owns this resource. |
ids | y | string | The IDor IDs (comma-delimited) of the resources to update. |
data | y | httpRequestBody | A substitution object to be updated. Supports partial updates - one or more fields may be included in the request and only the fields specified will be updated. To remove a field, the field must be explicitly passed with a null value. PUT is treated as PATCH as object replacement is not supported.. |
Example Request
Example Response
DELETE /scheduling/{organizationId}/substitutions/{ids}
Description
Delete scheduling substitution(s) for an organization by ID
(Unavailable/Replacement).
Return Type
substitution Object
Parameters
| Name | Required? | Data Type? | Description |
|---|---|---|---|
credentials | y | string | Basic Authorization header. |
organizationId | y | long | The ID of the Organization that owns this resource. |
ids | y | string | The IDor IDs (comma-delimited) of the resources to delete. |
Example Request
