Synchronizing availability between OnCall Health and your EMR/EHR

Availability is an object in OnCall Health's database that determines when patients are allowed to book sessions with providers through booking pages.

You can create, fetch, and edit availability objects through OnCall Health's API for the purpose of keeping provider schedules synchronized between systems.

Keep reading to learn more about the availability object and how it can be used in OnCall Health's external API.

Important

Before you proceed, it's important to note OnCall Health's availability object is only relevant if your organization's workflow involves patients scheduling appointments through an OnCall Health booking page. This includes white labelled booking pages.

If your organization schedules all appointments via API or within OnCall Health's administrative portal, you do not need to set availability. Appointments will be scheduled regardless of the provider's availability in these scenarios.

The logic is that our application would not get in the way of a provider or coordinator attempting to force a booking. The purpose of the availability object is to prevent patients from doing the same.

Contact your Customer Success Manager if you're not sure whether you need to use availability via OnCall Health's API.

About OnCall Health's availability object

See below for a breakdown of the OnCall Health availability object's API-accessible attributes.

Attribute

Description

starts_at

The datetime at which the availability should begin.

duration

How long (in minutes) the availability should last.

provider

The provider whose availability is being set with the availability record in question (each availability object can be associated with only one provider).

starts_at_timezone

The timezone in which you would like to set availability.

rrule

A recurrence rule determining the frequency (which must be WEEKLY), number of recurrences (which must be an integer), and days of the week (which must be SU, MO, TU, WE, TH, FR, or SA) the availability record in question applies to.

available

A boolean value indicating whether the availability object is active.

For example, an active hour-long availability starting at 9:00 AM EST on the 12 Mondays following January 1, 2022 would have the following API-accessible values.

Attribute

Value

starts_at

2022-01-01T14:00:00Z

duration

60

provider

https://api.oncallhealth.ca/providers/{id}/

starts_at_timezone

Canada/Eastern

rrule

FREQ=WEEKLY;COUNT=12;BYDAY=MO

available

true

Setting availability for a provider using OnCall Health's API

Here are the steps involved in setting availability for a provider using OnCall Health's API.

Step 1: Collect the necessary information

Here's a non-technical breakdown of what you need to collect to create an availability object using OnCall Health's API:

  • the datetime at which the availability window should open
  • how long (in minutes) the availability window should stay open
  • which OnCall Health provider the availability should be associated with
  • what timezone the availability should take place in
  • the number of weekly recurrences
  • what days of the week the availability should apply to

Once you've assembled these items, use them to form a POST request to OnCall Health's /appointmentavailabilities endpoint. The POST request's body should look something like this.

{
   "available":true,
   "starts_at":"2022-01-01T14:00:00Z",
   "duration":60,
   "provider":"https://api.oncallhealth.ca/providers/1/",
   "starts_at_timezone":"Canada/Eastern",
   "rrule":"FREQ=WEEKLY;COUNT=12;BYDAY=MO"
}

If your request is successful, you'll receive a response confirming the availability record has been created. If the associated provider logs into their OnCall Health account and visits the calendar, they'll also see the availability object represented there.

πŸ“˜

Tip

There's no limit on the number of availability objects you can create for a provider using OnCall Health's API. Availability can also overlap. Note: This does not enable overlapping appointments.

Fetching availability from OnCall Health's API

You can also fetch availabilities through OnCall Health's API.

To do this, simply make a GET request to OnCall Health's /appointmentavailabilities endpoint. The response body will contain a list of availabilities your API key has access to.

If you need to retrieve a specific availability in the future, you can store its ID and append it to future GET requests, making the endpoint /appointmentavailabilities/{id}.

Updating availability through OnCall Health's API

OnCall Health's API exposes availability in a bi-directional fashion, making it possible to keep availability synchronized between systems.

The ability to PATCH availabilities is a key component of this.

Availability attributes you can alter using PATCH requests include:

  • available
  • starts_at
  • starts_at_timezone
  • provider
  • rrule

What's next?

You should now understand how to POST, GET, and PATCH availability through OnCall Health's API. This is a very useful feature for any workflow that involves patients booking appointments through OnCall Health booking pages.

Explore our other guides via the left-hand sidebar for more information about building a comprehensive integration between an external system and OnCall Health.