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:

Shape	unavailability	recurrence	Use case
Ad-hoc availability	false	omitted / null	One-off clinic hours on a single date
Recurring availability	false	provided	Weekly repeating clinic hours between startDate and endDate
Ad-hoc unavailability	true	omitted / null	One-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 unavailability is a single date range: set startDate and endDate to the same calendar day (or span multiple days with a later endDate), plus startTime and endTime for the daily window.

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 — startDate is the first calendar day the rule can apply; endDate bounds the last calendar day (inclusive). For a single-day ad-hoc block, set endDate equal to startDate.
• Time window — startTime and endTime (HH:mm, 24-hour, zero-padded) apply on each matching recurrence day within the date range.
• 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",
    "endDate": "2026-07-01",
    "startTime": "09:00",
    "endTime": "12:00"
  }
}

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",
    "endDate": "2026-07-10",
    "startTime": "14:00",
    "endTime": "15:00"
  }
}

Do not include recurrence on this payload.

Input reference

Field	Required	Notes
unavailability	yes	true = blocked time; false = available time
room	yes	Practice location / room ID
user	no	Clinician ID; public API currently supports resourceType: user only
startDate	yes	YYYY-MM-DD
endDate	no	YYYY-MM-DD; defaults to null when omitted
startTime / endTime	yes	HH:mm (24-hour, zero-padded)
comment	no	Defaults to empty string
recurrence	no	Weekly rule; only with unavailability: false
exclusions	no	YYYY-MM-DD dates to skip within a recurrence

Validation errors

Situation	Message (summary)
Missing unavailability	Unavailability is required
Recurrence + unavailability	Cannot provide recurrence and \unavailability: true``
Empty daysOfTheWeek	Select at least one day of the week
Invalid date format	Start date must be in YYYY-MM-DD format
Invalid time format	Start time must be in HH:mm format
endDate before startDate	End date must be the same or after Start date
endTime not after startTime	End time must be after Start time
Unknown room	Room with id "…" not found.
Invalid user ID	User must be a valid ID

Migration from createOutOfOfficeBooking

On the New Semble Appointment System, replace createOutOfOfficeBooking with createAvailability and unavailability: true. Map the booking’s date/time range to startDate, endDate, startTime, and endTime, and set user and room to the clinician and location for the block.

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

• API reference: createAvailability
• API reference: ResourceAvailability
• How-to: Get started with the New Semble Appointment System
• Query: availabilitySlots — read computed slots after creating availability