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: