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.

1936

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

Provider

AttributeDescriptionAPI permissions
urlThe endpoint and primary key combination for accessing the providerRead only
full_nameThe provider's full nameRead only
emailThe provider's email addressRead only
membershipsAn array of OnCall Health divisions the provider is a member ofRead 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

AttributeDescriptionAPI permissions
urlThe endpoint and primary key combination for accessing the appointmentRead only
titleThe appointment's titleRead and write
datetimeThe appointment's scheduled date and timeRead and write
durationThe appointment's scheduled durationRead and write
typeThe appointment's type (online, inperson, phone, message)Read and write
statusThe appointment's completion statusRead and write
cancelledThe appointment's cancellation statusRead and write
divisionThe OnCall Health division the appointment is associated withRead and write
participantsAn array of the appointment's participantsRead and write
metadataA freeform field for attaching custom identifiers to the appointmentRead 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

AttributeDescriptionAPI permissions
urlThe endpoint and primary key combination for accessing the participantRead only
appointmentThe appointment the participant belongs toRead only
nameThe participant's nameRead and write
first_nameThe participant's first nameRead and write
last_nameThe participant's last nameRead and write
emailThe participant's email addressRead and write
feeHow much the participant will be charged for the appointmentRead and write
cancelledThe participant's cancellation statusRead and write
user_idThe primary key of the user associated with this participantRead

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

AttributeDescriptionAPI permissions
urlThe endpoint and primary key combination for accessing the roster contactRead only
nameThe roster contact's nameRead and write
emailThe roster contact's email addressRead and write
phoneThe roster contact's phone numberRead and write
sexThe roster contact's sexRead and write
date_of_birthThe roster contact's date of birthRead and write
custom_field_namesA freeform field for attaching custom identifiers to the appointmentRead and write
appointmentsAn array of the appointments the roster contact is a participant ofRead 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

AttributeDescriptionAPI permissions
urlThe endpoint and primary key combination for accessing the formRead only
titleThe form's titleRead only
skippableWhether patients can skip the formRead only
created_byThe provider who created the formRead 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

AttributeDescriptionAPI permissions
urlThe endpoint and primary key combination for accessing the form assignmentRead only
participantThe participant the form assignment belongs toRead and write
responseAn array of the participant's responses to the formRead 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: