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 four shapes:

Shape	`unavailability`	`recurrence`	`unavailabilityType`	Use case
Ad-hoc availability	`false`	omitted / `null`	omit	One-off clinic hours on a single date
Recurring availability	`false`	provided	omit	Weekly repeating clinic hours between `startDate` and `endDate`
Ad-hoc unavailability	`true`	omitted / `null`	required	One-off blocked time for that clinician in that room
Recurring unavailability	`true`	provided	required	Weekly blocked time for that clinician in that room

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. That rejection is what stops a continuous multi-day leave block: unavailability always covers startTime–endTime on one day, or on each day of a weekly series.

Recurring unavailability uses the same recurrence pattern as recurring availability. It still creates one user + room row. Each occurrence blocks that clinician in that room only.

`unavailabilityType`

unavailabilityType records why the time is blocked. Values match the Semble app (other, sickness, annualLeave, teamMeeting, oneToOneMeeting, clinicalAdmin, generalAdmin, cpd, induction, mandatoryTraining, siteEngagement, itOutage, managementTime, studyLeave, otherPaidLeave).

Unavailability (unavailability: true) — required, for both ad-hoc and recurring rows.
Availability (unavailability: false) — omit it. Sending a type is rejected.

`recurrence` (optional)

Provide recurrence for recurring availability or recurring unavailability. Omit the field or pass null for a single-day row.

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 a recurring series, startDate is the first calendar day the rule can apply and endDate bounds the last calendar day (inclusive). Omit endDate or pass null for an open-ended weekly series. 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,
    "unavailabilityType": "other",
    "user": "USER_ID",
    "room": "ROOM_ID",
    "startDate": "2026-07-10",
    "startTime": "14:00",
    "endTime": "15:00"
  }
}

Do not include recurrence or a multi-day endDate on this payload. unavailabilityType is required.

Recurring unavailability (`unavailability: true`)

Same weekly rule as recurring availability. unavailabilityType is required. Omit endDate for an open-ended series.

{
  "data": {
    "comment": "Weekly admin",
    "unavailability": true,
    "unavailabilityType": "generalAdmin",
    "user": "USER_ID",
    "room": "ROOM_ID",
    "startDate": "2026-07-01",
    "startTime": "09:00",
    "endTime": "12:00",
    "recurrence": {
      "frequency": "weekly",
      "interval": 1,
      "daysOfTheWeek": [1, 3]
    }
  }
}

The response endDate is null. Each Monday and Wednesday from 2026-07-01 onward is blocked from 09:00 to 12:00 for that clinician in that room. availabilityRule, availabilityRules, and availabilitySlots return and apply that series.

To end the series, pass endDate (YYYY-MM-DD, on or after startDate).

Input reference

Field	Required	Notes
`unavailability`	yes	`true` = blocked time; `false` = available time
`unavailabilityType`	conditional	Required when `unavailability` is true. Omit when `unavailability` is false
`room`	yes	`PracticeLocation.id`
`user`	no	Clinician ID; public API currently supports `resourceType: user` only
`startDate`	yes	`YYYY-MM-DD`
`endDate`	no	With `recurrence`: series end (`YYYY-MM-DD`), or omit/`null` for open-ended. Without `recurrence`: omit/`null` only; stored as `startDate`
`startTime` / `endTime`	yes	`HH:mm` (24-hour, zero-padded). Applied to each occurrence, including recurring unavailability
`comment`	no	Defaults to empty string
`recurrence`	no	Weekly rule for recurring availability or recurring unavailability
`exclusions`	no	`YYYY-MM-DD` dates to skip within a recurrence

Validation errors

Situation	Message (summary)
Missing `unavailability`	`Unavailability is required`
Unavailability without `unavailabilityType`	`Unavailability type is required when \`unavailability` is true`
`unavailabilityType` on availability	`Cannot provide \`unavailabilityType` when `unavailability` is false`
Unknown `unavailabilityType`	`Unavailability type must be a valid unavailability type`
`endDate` without `recurrence`	`End date must be omitted or null when recurrence is not provided`
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.

One day — ad-hoc unavailability (startDate, startTime, endTime, user, room; omit endDate and recurrence).
The same weekday window, repeating — recurring unavailability with recurrence, a required unavailabilityType, and optional endDate. Omit endDate for an open-ended weekly series.
Continuous all-day leave across calendar days — not represented by one row. Create one ad-hoc unavailability per day, or a weekly series whose startTime and endTime cover the blocked hours on the selected weekdays.

A recurring unavailability blocks that clinician in that room.

Summary​

unavailability (required)​

unavailabilityType​

recurrence (optional)​

Examples​

Ad-hoc availability​

Recurring availability​

Ad-hoc unavailability (unavailability: true)​

Recurring unavailability (unavailability: true)​

Input reference​

Validation errors​

Migration from createOutOfOfficeBooking​

See also​