Create Scheduling Substitutions

Scheduling 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

{
  "data": {
    "type": "staffSubstitution",
    "attributes": {
      "contactId": 1,
      "recurrence": {
        "type": "repeat",
        "datesApplicable": {
          "from": "2024-10-11", 
          "to": "2024-10-13"
        }
      },
      "staffAssignment": {
        "type": "contact", 
        "contactIds": [
          333333
        ]
      }, 
      "calendarId": 1
    }
  }
}

Unavailable

{
  "data": {
    "type": "staffSubstitution",
    "attributes": {
      "contactId": 1,
      "recurrence": {
        "type": "occurrence",
        "datesApplicable": {
          "from": "2024-10-11", 
          "to": "2024-10-13"
        }
      },
      "time": {
        "start": "07:00", 
        "end": "19:00"
      }, 
      "calendarId": 1
    }
  }
}

Substitution Fields

Return Type

substituions Object

Parameters