Understanding OnCall Health's API-accessible entities

Before you begin building an integration between OnCall Health and an external system, it helps to have an understanding of our platform's API-accessible entities (meaning those with dedicated endpoints) and how they relate to each other. That will be the topic of this guide.

An overview of OnCall Health's API-accessible entities

The diagram below provides a high-level overview of OnCall Health's API-accessible entities and how they relate to one another.

Next, let's explore each entity and its API-accessible attributes in greater detail.

Provider

Attribute	Description	API permissions
url	The endpoint and primary key combination for accessing the provider	Read only
full_name	The provider's full name	Read only
email	The provider's email address	Read only
memberships	An array of OnCall Health divisions the provider is a member of	Read only

A provider is a type of user in OnCall Health. It is analogous to a patient-facing professional within a healthcare organization. In a behavioural health institution with 100 therapists using OnCall Health, for example, each therapist would have their own provider record.

Tasks you'll likely perform through the API related to your organization's providers include:

Getting all providers
Getting a specific provider

Appointment

Attribute	Description	API permissions
url	The endpoint and primary key combination for accessing the appointment	Read only
title	The appointment's title	Read and write
datetime	The appointment's scheduled date and time	Read and write
duration	The appointment's scheduled duration	Read and write
type	The appointment's type (online, inperson, phone, message)	Read and write
status	The appointment's completion status	Read and write
cancelled	The appointment's cancellation status	Read and write
division	The OnCall Health division the appointment is associated with	Read and write
participants	An array of the appointment's participants	Read and write
metadata	A freeform field for attaching custom identifiers to the appointment	Read and write

An appointment is a record belonging to one provider. It represents a healthcare session between a provider and at least one patient.

Tasks you'll likely perform through the API related to your organization's appointments include:

Getting all appointments
Querying appointments based on status, date, and type
Getting a single appointment
Creating appointments
Updating existing appointments (including cancellations)

Participant

Attribute	Description	API permissions
url	The endpoint and primary key combination for accessing the participant	Read only
appointment	The appointment the participant belongs to	Read only
name	The participant's name	Read and write
first_name	The participant's first name	Read and write
last_name	The participant's last name	Read and write
email	The participant's email address	Read and write
fee	How much the participant will be charged for the appointment	Read and write
cancelled	The participant's cancellation status	Read and write
user_id	The primary key of the user associated with this participant	Read

A participant is a record belonging to one appointment. It is most commonly used to represent a patient's attendance (or expected attendance) at the associated appointment.

Tasks you'll likely perform through the API related to your organization's participants include:

Getting a single participant
Updating existing participants

Roster contact

Attribute	Description	API permissions
url	The endpoint and primary key combination for accessing the roster contact	Read only
name	The roster contact's name	Read and write
email	The roster contact's email address	Read and write
phone	The roster contact's phone number	Read and write
sex	The roster contact's sex	Read and write
date_of_birth	The roster contact's date of birth	Read and write
custom_field_names	A freeform field for attaching custom identifiers to the appointment	Read and write
appointments	An array of the appointments the roster contact is a participant of	Read only

A roster contact is a record associated with one division and one provider. It is most commonly used to represent a patient whose information needs to be stored outside the context of a single appointment.

Tasks you'll likely perform through the API related to your organization's roster contacts include:

Getting all roster contacts
Querying roster contacts based on name, email address, phone number, or custom fields
Getting a single roster contact
Creating roster contacts
Updating existing roster contacts
Deleting roster contacts

Form

Attribute	Description	API permissions
url	The endpoint and primary key combination for accessing the form	Read only
title	The form's title	Read only
skippable	Whether patients can skip the form	Read only
created_by	The provider who created the form	Read only

A form is a record associated with a provider or coordinator (another type of user that is not API accessible).

Tasks you'll likely perform through the API related to your organization's forms include:

Getting all forms
Getting a single form

Form assignments

Attribute	Description	API permissions
url	The endpoint and primary key combination for accessing the form assignment	Read only
participant	The participant the form assignment belongs to	Read and write
response	An array of the participant's responses to the form	Read only

A form assignment is a record indicating that a form has been assigned to a participant or roster contact.

Tasks you'll likely perform through the API related to your organization's form assignments include:

Getting a single form assignment
Creating form assignments
Deleting form assignments
Retrieving the contents of a completed form

Next steps

Now that you understand OnCall Health's API-accessible entities and how they relate to one another, you can begin confidently scoping and creating an integration between our platform and an external system (such as your EMR or EHR).

Not sure where to start? Check out these guides covering two of the most common integration scenarios: