Guides

Synchronizing patients between OnCall Health and your EMR/EHR

Suggest Edits

Among the most common uses for OnCall Health's API is synchronizing patients between OnCall Health and an electronic medical record (EMR) or electronic health record (EHR) system.

There are typically three main concerns when setting this synchronization up:

  1. Ensuring new patients successfully flow from the system of record into the system of engagement

  2. Ensuring patient updates in the system of record are reflected in the system of engagement as soon as possible

  3. Minimizing the amount of time spent manually reconciling records between the system of record and the system of engagement

In this guide, we'll walk you through the process of synchronizing patients between OnCall Health and an EMR or EHR in a way that addresses all three concerns.

Before you get started

Before proceeding, make sure you've met all of the requirements outlined on this page.

📘

A note regarding endpoints

Throughout this guide, the endpoints we'll reference follow this format https://api.oncallhealth.ca/{uri}. If your healthcare organization is based in the United States, change .ca to .us for each endpoint. We have separate servers in either country to ensure HIPAA and PHIPA compliance.

Terminology

There are two data models in OnCall Health that can be used to store information about patients:

  • participant: A participant belongs to a specific appointment. Their record contains basic information about them and their relationship to the appointment.

  • roster contact: A roster contact doesn't belong to a specific appointment. Rather, a patient's roster contact record can store appointment-agnostic information about them via customizable fields.

Any standard implementation of OnCall Health will require the creation of participant records. Whether you need to incorporate the creation and maintenance of roster contacts into your API integration as well depends on your organization's workflow. We'll cover the use of both models in this guide but contact your Customer Success Manager for more context.

Using your EMR or EHR as the system of record

If your EMR or EHR is the system of record, patient data should flow from there into OnCall Health. In this section, we'll cover the associated processes.

Pushing new patient data from your EMR or EHR to OnCall Health in the context of an appointment

Immediately after a new appointment record is created in your EMR or EHR, do the following.

Make a POST request to the https://api.oncallhealth.ca/appointments endpoint

See our documentation for this endpoint here.

Of note in this context is the participants parameter. This field accepts an array with one nested JSON object for each participant you'd like to create.

If your request is successful, you'll receive a response that looks like this from OnCall Health's API. Note the participants field containing patient data – if you passed multiple participants into this call, there would be one nested object for each of them.

{
   "url":"https://api.oncallhealth.ca/appointments/1234/",
   "title":"Sample API appointment",
   "datetime":"2026-01-15T0:00:00Z",
   "duration":60,
   "type":"online",
   "cancelled":false,
   "division":"https://api.oncallhealth.ca/divisions/123/",
   "participants":[
      {
         "url":"https://api.oncallhealth.ca/participants/56/",
         "email":"[email protected]",
         "name":"Test Patient",
         "first_name":"Test",
         "last_name":"Patient",
         "fee":10,
         "cancelled":false
      }
   ],
   "metadata":{
      "patient_emr_id":"12345"
   }
}

We recommend storing each participant's URL (i.e. https://api.oncallhealth.ca/participants/56/ in the example above) in their corresponding record in your EMR or EHR if possible. This will make it easy to reconcile the two records later on. You can use the metadata field in an OnCall Health appointment record for the same purpose.

Pushing new patient data from your EMR or EHR to OnCall Health outside the context of an appointment

If your workflow doesn't necessitate storing information about a patient in OnCall Health beyond the context of a specific appointment, you can skip this section.

Otherwise, immediately after an appointment-agnostic patient record is created in your EMR or EHR, do the following.

Make a POST request to the https://api.oncallhealth.ca/contacts/ endpoint

This endpoint allows you to create a new roster contact in OnCall Health. See our documentation for this endpoint here.

There are four parameters worth noting:

  • provider: Each roster contact in OnCall Health must belong to a provider. Contact your Customer Success Manager if you're unsure what value to place here.
  • division: Each roster contact in OnCall Health must also belong to a division. Once again, contact your Customer Success Manager if you need more context.
  • custom_fields: This is an optional parameter you can use to store key/value pairs of your choosing related to a particular patient. Organizations often use this parameter to store a reference to the patient's corresponding EMR or EHR record. We strongly recommend doing this as it will make reconciling records later much easier.
  • notes: This is another optional parameter you can use to store freeform notes related to a particular patient.

Here's an example of a successful response you'd receive upon creating a roster contact through OnCall Health's API.

{
   "id":12345,
   "division":"https://api.oncallhealth.ca/divisions/2404/",
   "provider":"https://api.oncallhealth.ca/providers/196157/",
   "url":"https://api.oncallhealth.ca/contacts/313751/",
   "name":"Brandon Newpatient",
   "first_name":"Jane",
   "last_name":"Doe",
   "email":"[email protected]",
   "phone":null,
   "notes":null,
   "sex":"male",
   "date_of_birth":null,
   "appointments":"https://api.oncallhealth.ca/contacts/12345/appointments/",
   "custom_field_names":{
      "2":"EMR id",
      "6":"Has submitted forms?"
   },
   "custom_field_values":{
      "2":"Ax1A2",
      "6":true
   }
}

Pushing patient record updates from your EMR or EHR to OnCall Health in the context of an appointment

As mentioned a few times throughout this guide, a patient's participant record in OnCall Health contains basic information about them and their relationship to a specific appointment. Consequently, you would only need to update a participant record if any of the following fields' values have changed:

  • name
  • email
  • fee
  • cancelled
  • first_name
  • last_name

Immediately after any of these fields is updated in your EMR or EHR, do the following.

Make a PATCH request to the https://api.oncallhealth.ca/participants/{id}/ endpoint

Replace {id} with the OnCall Health ID for that participant. This should be easy if you were able to store the participant's ID in the corresponding EMR or EHR record as we recommended earlier.

If you weren't able to store the participant ID, you'd need to find it some other way, which likely won't be as reliable as our recommended method since we don't support querying participants directly through the OnCall Health API.

In the body of this PATCH request, pass whatever parameters you'd like to update. See our documentation for this endpoint here.

Here's an example of a successful response you'd receive after updating a participant.

{
   "url":"https://api.oncallhealth.ca/participants/12345/",
   "appointment":"https://api.oncallhealth.ca/appointments/12345/",
   "name":"Test Patient",
   "first_name":"Test",
   "last_name":"Patient",
   "email":"[email protected]",
   "fee":10.0,
   "cancelled":false,
   "user_id":2
}

Pushing patient record updates from your EMR or EHR to OnCall Health outside the context of an appointment

Immediately after an appointment-agnostic patient record is updated in your EMR or EHR, do the following.

Make a PATCH request to the https://api.oncallhealth.ca/contacts/{id}/ endpoint

Replace {id} with the OnCall Health ID for that participant. This will be easy if you stored the ID in the corresponding EMR or EHR record. You can also query contacts by name, email, or phone number (see documentation here).

In the body of this PATCH request, pass whatever parameters you'd like to update. See our documentation for this endpoint here.

Pay attention to the notes and custom_fields parameters. You can push data from your EMR or EHR into one of these customizable fields if it doesn't correspond neatly with one of the standard options.

Here's an example of a successful response you'd receive after updating a roster contact.

{
   "id":12345,
   "division":"https://api.oncallhealth.ca/divisions/12345/",
   "provider":"https://api.oncallhealth.ca/providers/12345/",
   "url":"https://api.oncallhealth.ca/contacts/12345/",
   "name":"Jane Doe",
   "first_name":"Jane",
   "last_name":"Doe",
   "email":"[email protected]",
   "phone":"1234567890",
   "notes":null,
   "sex":"female",
   "date_of_birth":"1980-01-02",
   "appointments":"https://api.oncallhealth.ca/contacts/12345/appointments/",
   "custom_field_names":{
      "1":"EMR id"
   },
   "custom_field_values":{
      "1":"12345"
   }
}

Using OnCall Health as the system of record

OnCall Health is not designed to be an EMR or EHR. Consequently, using it as the system of record for patient data only makes sense in limited circumstances (particularly if you have an EMR or EHR). In this section, we'll cover the processes associated with creating an integration in those rare circumstances.

Pushing new patient data from OnCall Health into your EMR or EHR in the context of an appointment

OnCall Health has the ability to fire a webhook upon appointment creation. When your system receives this webhook, do the following.

Step 1: Make a GET request using the OnCall Health appointment reference from the webhook request body

Here's an example of a webhook request body indicating the creation of a new appointment in OnCall Health.

{
   "event":"appointment_created",
   "url":"https://api.oncallhealth.com/appointments/1"
}

Use the URL parameter (https://api.oncallhealth.com/appointments/1 in the above example) in your call. This will return the appointment's data. Here's an example of a successful response.

{
   "url":"https://api.oncallhealth.ca/appointments/1/",
   "title":"My sample appointment",
   "datetime":"2019-01-16T18:00:00Z",
   "duration":60,
   "type":"online",
   "status":"Complete",
   "cancelled":false,
   "division":"https://api.oncallhealth.ca/divisions/123/",
   "participants":[
      {
         "url":"https://api.oncallhealth.ca/participants/12345/",
         "appointment":"https://api.oncallhealth.ca/appointments/12345/",
         "name":"Test Patient",
         "first_name":"Test",
         "last_name":"Patient",
         "email":"[email protected]",
         "fee":10.0,
         "cancelled":false,
         "user_id":2
      }
   ],
   "metadata":null
}

Step 2: Iterate through the participants field and create new records in your EMR or EHR accordingly

The participants field contains an array of participants associated with the OnCall Health appointment. You can iterate through this array and retrieve each participant's data, including a reference to their record in OnCall Health (the URL field – https://api.oncallhealth.ca/participants/12345/ in the example above).

We recommend storing each participant's reference in their EMR or EHR record. This will make reconciling the records easy later on.

Pushing new patient data from OnCall Health into your EMR or EHR outside the context of an appointment

OnCall Health does not offer webhooks associated with roster contacts. Consequently, your system will need to check in with OnCall whenever it wants to scrape for new patients. Whether this scrape takes place as part of a daily cron job or some other mechanism is up to you. Regardless, here's what should happen when a scrape is initiated.

Step 1: Make a GET request to the https://api.oncallhealth.ca/contacts/ endpoint

This will return an object containing all roster contacts associated with your API key. Here's an example of a successful response.

{
   "count":100,
   "next":"https://api.oncallhealth.ca/contacts/?page=2",
   "previous":null,
   "results":[
      {
         "url":"https://api.oncallhealth.ca/contacts/1234/",
         "name":"Jane Doe",
         "email":"[email protected]",
         "phone":"2125551542",
         "sex":"Unknown",
         "date_of_birth":"1970-01-01",
         "custom_field_names":{
            "2":"EMR id",
            "6":"Has submitted forms?"
         },
         "custom_field_values":{
            "2":"Ax1A2",
            "6":true
         },
         "appointments":"https://api.oncallhealth.ca/contacts/1234/appointments/"
      }
   ]
}

Step 2: Iterate through the collection of roster contacts and create records in your EMR or EHR accordingly

When creating new patient records in your EMR or EHR, we recommend storing the OnCall Health URL parameter (see example response above) in those records. This will make reconciling records between OnCall Health and your EMR or EHR easy later on.

Note: You should also follow the steps above to push patient roster contact updates from OnCall Health into your EMR or EHR.

Pushing patient record updates from OnCall Health to your EMR or EHR in the context of an appointment

Whenever an appointment is updated in OnCall Health (including changes to participants), we have the ability to fire a webhook. Here's an example of a webhook request body indicating an OnCall Health appointment has been updated.

{
  "event": "appointment_updated",
  "url": "https://api.oncallhealth.com/appointments/1"
}

When your system receives this webhook request, do the following.

Step 1: Make a GET request using the OnCall Health appointment reference from the webhook request body

The appointment reference is the URL parameter in the webhook request body. Here's an example of a successful response.

{
   "url":"https://api.oncallhealth.ca/appointments/1/",
   "title":"My sample appointment",
   "datetime":"2019-01-16T18:00:00Z",
   "duration":60,
   "type":"online",
   "status":"Complete",
   "cancelled":false,
   "division":"https://api.oncallhealth.ca/divisions/123/",
   "participants":[
      {
         "url":"https://api.oncallhealth.ca/participants/12345/",
         "appointment":"https://api.oncallhealth.ca/appointments/12345/",
         "name":"Test Patient",
         "first_name":"Test",
         "last_name":"Patient",
         "email":"[email protected]",
         "fee":10.0,
         "cancelled":false,
         "user_id":2
      }
   ],
   "metadata":null
}

It's worth noting that the response doesn't provide context regarding what changed about the appointment. If you're using OnCall Health as the system of record, however, you'd need to update your EMR or EHR's record to ensure it matches the response.

Next steps

Patient data is among the most common types of information that need to be synchronized between OnCall Health and external systems. We hope this guide has been helpful in showing you how to achieve a sync.

If you encounter errors during this process, refer to this section of our API documentation. If you're unable to resolve the issue, contact your Customer Success Manager with a description of the issue (including error messages) so they can assist you.

Updated about 3 years ago