Referrals API Overview

Referrals API Overview


* With Medfusion Referrals API, you can keep new and updated referrals information synchronized between a practice EMR/PM system and Medfusion systems. The exchanged information can include:

  • Referral reason
  • Referral source and destination practice or staff
  • Referral text description
  • Comments
  • Attachments

* Medfusion APIs will follow the standard ISO8601 formats for all time elements, unless otherwise noted ( The standard format will include the timezone. For UTC (the preferred time zone to be used for timestamps), the time zone is specified as ‘Z’. The API documentation will clearly specify any deviation from the ISO8601 recommendation.


Referrals workflow usually start for practice when they want to create new referral. To be able to create new referral practice needs to know who referral will be sent to and what type of referral it is. Integrations should once a day do GET /referral-types and GET /contacts to get a list of possible referral types and contacts (destination practices and staff) that can be used by practice.


Once practice created a referral by calling POST /referrals they will need to receive updates from other practice. Practice/integration should call GET /referrals every 10 minutes to get updates for incoming or outgoing referral. If there are new attachments then GET /referrals/<uuid>/attachments/<uuid>/content should be used to retrieve attachment content. Since attachments cant’ change it is necessary to call it only once for each attachment.

Practice that created a referral usually wants to know when destination practice read it. This is accomplished by destination practice calling POST /referrals/<uuid>/status-update and update status to “Viewed” once a personnel in destination practice first opened it.

Practices (both originating and destination) needs to exchange data between them in context of the referral. This is accomplished by calling POST /referrals/<uuid>/attachments to add new attachment or POST /referrals/<uuid>/comments to add new comment.


Referral statuses

Referral goes through different statuses during its lifetime.

When referral is create it will always have status “Open”

As mentioned destination practice needs to change status to “Viewed” once user open referral for first time.

Destination practice can later change status from “Viewed” to following statuses:

  •  Appointment Scheduled
  • Appointment Not Scheduled – Patient Refused
  • Appointment Not Scheduled – See Comments
  • No Show
  • Disregarded – See Comments
  • Completed

Referrals with status “Completed” or “Disregarded – See Comments” should not be updated anymore and are considered closed.

Sending practice has only one status it can change referrals to “Disregarded – See Comments” to mark them closed. There can be multiple reasons why sending practice would like to cancel referral For eg. “Referral is not needed anymore” or “Referral was sent to wrong receiver”.