Pushing form data from OnCall Health into your EMR or EHR
Forms are commonly used to collect patient data (i.e. mental health assessments) in OnCall Health. Pulling that data out of OnCall Health and into your electronic medical record (EMR) or electronic health record (EHR) system is easy thanks to OnCall Health's public API.
In this guide, we'll cover the common use cases for this integration and provide instructions for the entire form assignment lifecycle.
You'll learn:
- how to assign forms using OnCall Health's API
- how to retrieve data from completed forms using OnCall Health's API
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.
Creating a form assignment in OnCall Health
Providers and coordinators can assign patients forms through OnCall Health's frontend. Check out this article in our knowledge base for instructions.
You can also assign forms through OnCall Health's API using the following steps.
Step 1: Identify the form you would like to assign
To see a list of all forms associated with your account, make a GET request to the https://api.oncallhealth.ca/forms/ endpoint.
Here's a sample response.
{
"count":100,
"next":"https://api.oncallhealth.ca/forms/?page=2",
"previous":null,
"results":[
{
"url":"https://api.oncallhealth.ca/forms/1234/",
"title":"PHQ-9 Intake form",
"skippable":true,
"created_by":"https://api.oncallhealth.ca/providers/1234/",
"created_at":"2019-01-16T18:00:00Z"
},
{
"url":"https://api.oncallhealth.ca/forms/1235/",
"title":"GAD-7",
"skippable":true,
"created_by":"https://api.oncallhealth.ca/providers/1234/",
"created_at":"2019-01-16T18:00:00Z"
}
]
}
Retrieve the URL of the form you'd like to assign before moving onto the next step.
Step 2: Identify the appointment participant or roster contact you'd like to assign the form to
There are two contexts in which you can assign forms.
The first is in the context of a specific appointment. Think of GAD-7 assessments that need to be completed before every appointment. In this scenario, the form assignment is associated with an appointment participant whose URL you will need to retrieve.
The second is a general context in which the form does not need to be associated with a particular appointment. Think of a general intake or insurance form that only needs to be completed once. In this scenario, the form assignment is associated with a roster contact whose URL you will need to retrieve.
Retrieving an appointment participant to create an appointment-specific form assignment
Start by making a GET request to the https://api.oncallhealth.ca/appointments/ endpoint. This will return a list of appointments associated with your account. Here's an example response.
{
"count":100,
"next":"https://api.oncallhealth.ca/appointments/?page=3",
"previous":"https://api.oncallhealth.ca/appointments/?page=1",
"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":null
},
{
"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":null
}
]
}
Identify the appointment whose participant needs to be assigned a form. Then, look in that appointment's participants field and retrieve the desired participant's URL.
Retrieving a roster contact to create an appointment-agnostic form assignment
Start by making a GET request to the https://api.oncallhealth.ca/contacts/ endpoint. This will return a list of roster contacts associated with your account. Here's an example 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/"
}
]
}
You can also add query parameters to your request URL and search for providers by name, email address, phone, or custom fields.
Retrieve your desired roster contact's URL before proceeding to the next step.
Step 3: Make a POST request to the https://api.oncallhealth.ca/formassignment/ endpoint
This endpoint requires two parameters (both of which we obtained in the previous two steps):
- form
- participant OR contact
Here's an example response indicating your form has been assigned successfully.
{
"url":"https://api.oncallhealth.ca/formassignment/123/",
"schema":{
},
"participant":"https://api.oncallhealth.ca/participants/223/",
"contact":null,
"results":[
]
}
Pulling data from a completed OnCall Health form into your EMR or EHR
When an assigned form is completed, OnCall Health can fire a webhook notifying your system. Contact your Customer Success Manager for assistance setting this webhook up.
Here's what to do after receiving that webhook request.
Step 1: Make a GET request to the https://api.oncallhealth.com/formassignments/id endpoint using the webhook body's reference
Here's an example of a webhook request body you'd receive when a patient completes a form.
{
"event":"form_completed",
"url":"https://api.oncallhealth.com/formassignments/1"
}
Making a GET request using the URL parameter will result in a response that looks like this.
{
"url":"https://api.oncallhealth.ca/formassignment/123/",
"schema":{
},
"participant":"https://api.oncallhealth.ca/participants/223/",
"response":[
"answer 1",
"5",
null,
"answer 3"
]
}
Step 2: Port data from the response parameter into your EMR or EHR as needed
The response parameter is an array containing the patient's responses to each of the form questions.
The exact steps involved in porting these fields into your EMR or EHR will vary on that application. Refer to your EMR or EHR's API documentation from here.
Next steps
You should now have a solid understanding of how to work with forms and form assignments in OnCall Health.
Forms are just one type of record you can access through OnCall Health's API. Here are some additional guides you may find useful while integrating OnCall Health with your EMR or EHR:
Updated about 3 years ago