Skip to main content

Resource availability — createAvailability mutation

Users can create clinician availability and unavailability blocks at a practice room through the public API.

Affected mutation: createAvailability

Availability: Practices using the New Semble Appointment System only. The mutation is not available on the legacy appointment system.

Summary​

createAvailability persists an availability row for a clinician (user) at a PracticeLocation (room). Each call creates one of three shapes:

ShapeunavailabilityrecurrenceUse case
Ad-hoc availabilityfalseomitted / nullOne-off clinic hours on a single date
Recurring availabilityfalseprovidedWeekly repeating clinic hours between startDate and endDate
Ad-hoc unavailabilitytrueomitted / nullOne-off blocked time (out of office, leave, etc.)

Recurring unavailability is not supported: you cannot send recurrence when unavailability is true.

The response is a ResourceAvailability object under data.

unavailability (required)​

unavailability is a required boolean on CreateResourceAvailabilityInput.

  • unavailability: false — marks time the clinician is available for booking at the given room. Use for clinic hours and other bookable windows.
  • unavailability: true — marks time the clinician is not available at the given room. This blocks booking for that user/room during the window. It replaces createOutOfOfficeBooking for practices on the New Semble Appointment System.

Ad-hoc availability and unavailability are single-day rows. Omit endDate (or pass null); the API stores endDate as startDate. Sending any other endDate without recurrence is rejected.

Constraint: unavailability: true and recurrence cannot be used together. The API returns:

Cannot provide recurrence and \unavailability: true``

For recurring blocked time, create separate ad-hoc unavailability entries per occurrence, or use product/UI workflows until recurring unavailability is supported on the API.

recurrence (optional)​

Provide recurrence only when creating recurring availability (unavailability: false). Omit the field or pass null for ad-hoc availability or any unavailability.

recurrence: {
  frequency: weekly   # only supported value
  interval: Int!        # e.g. 1 = every week, 2 = every two weeks
  daysOfTheWeek: [Int!]! # 0 (Sunday) through 6 (Saturday); at least one day required
}

Behaviour:

  • Frequency — only weekly is accepted. Other values are rejected at validation.
  • Interval — positive whole number. 1 repeats every week on the selected weekdays; 2 every two weeks, and so on.
  • Days of the week — weekday indices in the recurrence rule. At least one day is required; an empty list returns Select at least one day of the week.
  • Date range — for recurring availability, startDate is the first calendar day the rule can apply and endDate bounds the last calendar day (inclusive). For ad-hoc rows (no recurrence), omit endDate or pass null; the stored value becomes startDate.
  • Time window — startTime and endTime (HH:mm, 24-hour, zero-padded) apply on each matching recurrence day within the date range (or on the single ad-hoc day).
  • Exclusions — optional exclusions: [String!] lists calendar dates (YYYY-MM-DD) to skip within the rule (RFC 5545-style exception dates). Omitted or null is stored as an empty list. Returned exclusions on ResourceAvailability are ISO 8601 UTC instants.

When recurrence is omitted, the created row is ad-hoc: recurrence is null in the response.

Examples​

Ad-hoc availability​

mutation CreateAdHocAvailability($data: CreateResourceAvailabilityInput!) {
  createAvailability(data: $data) {
    data {
      id
      unavailability
      recurrence {
        frequency
        interval
        daysOfTheWeek
      }
      startDate
      endDate
      startTime
      endTime
      user {
        id
      }
      room {
        id
      }
    }
  }
}

Variables:

{
  "data": {
    "comment": "Morning clinic",
    "unavailability": false,
    "user": "USER_ID",
    "room": "ROOM_ID",
    "startDate": "2026-07-01",
    "startTime": "09:00",
    "endTime": "12:00"
  }
}

Omit endDate. The response endDate will be 2026-07-01 (equal to startDate).

Recurring availability​

{
  "data": {
    "comment": "Weekly clinic",
    "unavailability": false,
    "user": "USER_ID",
    "room": "ROOM_ID",
    "startDate": "2026-07-01",
    "endDate": "2026-09-30",
    "startTime": "09:00",
    "endTime": "17:00",
    "recurrence": {
      "frequency": "weekly",
      "interval": 1,
      "daysOfTheWeek": [1, 3, 5]
    },
    "exclusions": ["2026-08-15"]
  }
}

daysOfTheWeek: [1, 3, 5] is Monday, Wednesday, and Friday. Align weekdays with your startDate/endDate range in the practice timezone context used for scheduling.

Ad-hoc unavailability (unavailability: true)​

{
  "data": {
    "comment": "Out of office",
    "unavailability": true,
    "user": "USER_ID",
    "room": "ROOM_ID",
    "startDate": "2026-07-10",
    "startTime": "14:00",
    "endTime": "15:00"
  }
}

Do not include recurrence or endDate on this payload. For blocked time spanning multiple days, create one ad-hoc unavailability per calendar day.

Input reference​

FieldRequiredNotes
unavailabilityyestrue = blocked time; false = available time
roomyesPracticeLocation.id
usernoClinician ID; public API currently supports resourceType: user only
startDateyesYYYY-MM-DD
endDatenoWith recurrence: series end (YYYY-MM-DD), or omit/null for open-ended. Without recurrence: omit/null only; stored as startDate
startTime / endTimeyesHH:mm (24-hour, zero-padded)
commentnoDefaults to empty string
recurrencenoWeekly rule; only with unavailability: false
exclusionsnoYYYY-MM-DD dates to skip within a recurrence

Validation errors​

SituationMessage (summary)
Missing unavailabilityUnavailability is required
Recurrence + unavailabilityCannot provide recurrence and \unavailability: true``
endDate without recurrenceEnd date must be omitted or null when recurrence is not provided
Empty daysOfTheWeekSelect at least one day of the week
Invalid date formatStart date must be in YYYY-MM-DD format
Invalid time formatStart time must be in HH:mm format
endDate before startDateEnd date must be the same or after Start date
endTime not after startTimeEnd time must be after Start time
Unknown roomRoom with id "…" not found.
Invalid user IDUser must be a valid ID

Migration from createOutOfOfficeBooking​

On the New Semble Appointment System, replace createOutOfOfficeBooking with createAvailability and unavailability: true. Map each calendar day of the booking’s range to its own ad-hoc create (startDate, startTime, endTime, user, room; omit endDate). Multi-day out-of-office periods require one row per day.

Recurring out-of-office patterns from the legacy API are not mirrored by recurring unavailability on createAvailability; use ad-hoc unavailability per occurrence or manage blocks in Semble until a dedicated API is available.

See also​