Skip to main content

Resource availability — availabilityRule query

Integrations can fetch a persisted clinician availability or unavailability block by ID through the public API.

Affected query: availabilityRule

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

Summary​

availabilityRule returns a single ResourceAvailability row under data, identified by the id returned from createAvailability or stored from a prior sync.

Use it to:

  • Confirm what was persisted after creating availability or unavailability
  • Re-read recurrence, exclusions, and date/time fields for a known rule ID
  • Resolve rule metadata (comment, unavailability, user, room, audit fields) without listing all rules

This query returns the stored rule definition, not computed bookable slots. For slot-based reads, use availabilitySlots.

Input​

QueryAvailabilityRuleInput has one required field:

FieldRequiredNotes
idyesResource availability ID

Response​

The payload shape is ResourceAvailabilityRuleQueryPayload:

{
  availabilityRule(data: { id: "RULE_ID" }) {
    data {
      id
      comment
      unavailability
      resourceType
      user {
        id
      }
      room {
        id
      }
      recurrence {
        frequency
        interval
        daysOfTheWeek
      }
      exclusions
      startDate
      endDate
      startTime
      endTime
      createdAt
      updatedAt
      createdBy
      lastUpdatedBy
    }
  }
}

Field behaviour matches createAvailability:

  • unavailability — false for availability (bookable time); true for unavailability (blocked time).
  • recurrence — null for ad-hoc rules; populated for recurring availability (frequency, interval, daysOfTheWeek).
  • exclusions — ISO 8601 UTC instants for dates skipped within a recurrence rule; empty array when none.
  • startDate / endDate / startTime / endTime — persisted calendar and daily window values (YYYY-MM-DD and HH:mm).
  • user / room — clinician and practice location for the rule.
  • createdAt / updatedAt / createdBy / lastUpdatedBy — audit metadata for the row.

Examples​

Fetch an ad-hoc availability rule​

query GetAvailabilityRule($data: QueryAvailabilityRuleInput!) {
  availabilityRule(data: $data) {
    data {
      id
      comment
      unavailability
      recurrence {
        frequency
        interval
        daysOfTheWeek
      }
      startDate
      endDate
      startTime
      endTime
      user {
        id
      }
      room {
        id
      }
    }
  }
}

Variables:

{
  "data": {
    "id": "RULE_ID"
  }
}

For ad-hoc availability created with createAvailability, expect unavailability: false and recurrence: null.

Fetch a recurring availability rule​

Use the same query with the id from a recurring createAvailability call. Expect recurrence with frequency: weekly, a positive interval, and at least one entry in daysOfTheWeek (0 = Sunday through 6 = Saturday). exclusions lists any skipped dates as ISO 8601 strings.

Fetch an ad-hoc unavailability rule​

Query by the id of a row created with unavailability: true. Expect recurrence: null and unavailability: true.

Validation errors​

SituationMessage (summary)
Missing idField "id" of required type "ID!" was not provided
Invalid id formatID must be a valid ID
Unknown or other-practice ruleResource availability with id "…" not found.

Rules are scoped to the authenticated practice. A valid ObjectId that does not exist in the practice returns the not-found error.

Permissions​

The query requires the settingsAvailabilities permission (same as createAvailability).

Integration guidance​

  • Store id from createAvailability: Use the mutation response data.id as the lookup key until availabilityRules (list) is available.
  • Do not use for slot discovery: Prefer availabilitySlots when you need computed availability windows for booking flows.
  • Idempotent reads: Safe to retry; the query does not mutate state.

See also​