Guides

Synchronizing appointments between OnCall Health and your EMR/EHR

Suggest Edits

Among the most common uses for OnCall Health's API is synchronizing appointments 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 appointments successfully flow from the system of record into the system of engagement

  2. Ensuring appointment 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 appointments 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.

Using your EMR or EHR as the system of record

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

Pushing appointment creations from your EMR or EHR into OnCall Health

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

This call will create an appointment record in OnCall Health based on the body parameters you supply (see this endpoint's documentation here for a full list of parameters).

There are a few parameters worth highlighting for the purpose of this guide:

  • division: This field expects the URL associated with the OnCall Health Division you're looking to create an appointment in. Contact your Customer Success Manager for more information if you're unsure about what this is.
  • provider: This field expects the URL associated with the OnCall Health Provider you're looking to create an appointment for. Once again, contact your Customer Success Manager if you need clarification.
  • metadata: This field is optional. However, strongly consider populating it with the unique reference to the associated appointment record in your EMR or EHR (i.e. its primary key). This will make your life much easier when you attempt to reconcile differences between OnCall Health and your EMR or EHR.

If your request is successful, you'll receive a response containing the new OnCall Health appointment's data.

Here's what that response would look like.

{
   "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":{
      "emr_id":"12345"
   }
}

If appointment records in your EMR or EHR accept metadata, consider storing the url portion of the above response there. This is another measure to help you easily match an appointment in OnCall Health with its counterpart in your EMR or EHR later on.

Pushing appointment updates (including cancellations) from your EMR or EHR into OnCall Health

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

This will return a list of all OnCall Health appointments accessible via your API key. Here's what that response might look like.

{
   "count":100,
   "next":"https://api.oncallhealth.ca/appointments/?page=2",
   "previous":"https://api.oncallhealth.ca/appointments/?page=3",
   "results":[
      {
         "url":"https://api.oncallhealth.ca/appointments/12345/",
         "title":"My appointment 1",
         "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/102/",
               "appointment":"https://api.oncallhealth.ca/appointments/12345/",
               "name":"Test Patient",
               "first_name":"Test",
               "last_name":"Patient",
               "email":"[email protected]",
               "fee":10.0,
               "cancelled":false
            }
         ],
         "metadata":{
            "emr_id":"12345"
         }
      },
      {
         "url":"https://api.oncallhealth.ca/appointments/123456/",
         "title":"My appointment 2",
         "datetime":"2019-01-21T21:28:00Z",
         "duration":15,
         "type":"online",
         "status":"Provider cancelled",
         "cancelled":true,
         "division":"https://api.oncallhealth.ca/divisions/123/",
         "participants":[
            {
               "url":"https://api.oncallhealth.ca/participants/100/",
               "appointment":"https://api.oncallhealth.ca/appointments/12346/",
               "name":"Test Patient",
               "first_name":"Test",
               "last_name":"Patient",
               "email":"[email protected]",
               "fee":10.0,
               "cancelled":false,
               "user_id":2
            }
         ],
         "metadata":{
            "emr_id":"123456"
         }
      }
   ]
}

Step 2: Find the appointment you're looking to update

If you follow our advice from the previous section and include in the metadata section for each OnCall Health appointment a reference to its associated record in your EMR or EHR, this should be easy. Just select the record with the reference you're looking for.

If you don't follow that advice, you'll need to use some less reliable means of finding the correct record (i.e. matching the appointment's title, provider, participant, and date). This is not recommended – store a reference in the metadata and you'll have a much easier time.

Step 3: Update the OnCall Health appointment record

This will require a PATCH call to the https://api.oncallhealth.ca/appointments/{id}/ endpoint. Replace {id} with the OnCall Health ID of the record you identified in Step 2.

See our documentation for this endpoint (including the parameters available when updating an appointment in OnCall Health) here. You only need to provide the body parameters you'd like to update.

Using OnCall Health as the system of record

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

Pushing appointment creations from OnCall Health into your EMR or EHR

Step 1: Ensure your EMR, EHR, or middleware is configured to receive "appointment_created" webhook requests

When an appointment is created in OnCall Health, we can trigger a webhook request and send it to a URL of your choosing. Contact your Customer Success Manager for more information and to set this up.

Here's what an "appointment_created" webhook request body would look like.

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

Step 2: Upon webhook request receipt, do the following

The url portion of the "appointment_created" webhook request body will contain a reference to the associated OnCall Health appointment record. Grab the latter portion of that reference (the numeric part) and make a GET call to the https://api.oncallhealth.ca/appointment/{id}/ endpoint. Substitute {id} with the numeric reference from your webhook request body's url parameter.

You'll receive a response that looks like this and contains the information associated with that appointment record in OnCall Health.

{
   "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":{
      "emr_id":"12345"
   }
}

Step 3: Use the response to create a record in your EMR or EHR

The exact process will vary depending on your EMR or EHR. If appointments in your EMR or EHR are capable of storing metadata, consider placing the associated OnCall Health record's ID (the same one you used to make the call in Step 2) there.

Appointments in OnCall Health are capable of storing metadata. Consider placing a unique identifier for the associated EMR or EHR record (i.e. its primary key) in this field.

This will make it easier to match the records later on.

Pushing appointment updates from OnCall Health into your EMR or EHR

Step 1: Ensure your EMR, EHR, or middleware is configured to receive "appointment_updated" webhook requests

When an appointment is updated in OnCall Health, we can trigger a webhook request and send it to a URL of your choosing. Contact your Customer Success Manager for more information and to set this up.

Here's what an "appointment_updated" webhook request would look like.

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

Step 2: Upon webhook request receipt, do the following

The url portion of the "appointment_updated" webhook request body will contain a reference to the associated OnCall Health appointment record. Grab the latter portion of that reference (the numeric part) and make a GET call to the https://api.oncallhealth.ca/appointment/{id}/ endpoint. Substitute {id} with the reference from your webhook request body's url parameter.

You'll receive a response that looks like this and contains the information associated with that appointment record in OnCall Health.

{
   "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":{
      "emr_id":"12345"
   }
}

Step 3: Use the response to update the associated record in your EMR or EHR

Identifying this associated record in your EMR or EHR should be easy if you take our advice in the previous section and include a unique reference to that object in the OnCall Health appointment record's metadata field. You could then simply retrieve that reference and use it to find the record.

Next steps

Appointments are among the most common records that need to be synchronized between OnCall Health and external systems. We hope this guide has been helpful in showing you how to achieve this synchronization.

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 over 3 years ago