Request Records - Full

SUMMARY

Greenlight divides medical record order data into three objects:

• Patient - data about the person, your customer (first name, last name, date of birth, etc.)
• Order - your organization's ids related to this set of medical records (claim #s, account #s, MRN, etc.)
• Requests - data about each medical facility from which you need records (facility name, address, phone, etc.)

There are three API endpoints for ordering records:

• Create Patient - for sending patient demographic information
• Create Order (with Requests) - for sending your Order Id and the Request data for each healthcare facility which has records you are requesting. You can send information about the Order and Requests in this single API call.
• Add Requests (to an existing Order) - for adding additional Requests to an Order sent previously

TWO APPROACHES to RECORD REQUESTS

While all integration paths require you to send Patient and Order data to start the process, there are two ways you can handle Requests (the details about the locations of the medical records).

• You collect it. You can collect this information from the patient in your application, and send it to Greenlight using the Greenlight API. This way, when the patient is redirected to the Greenlight app for consent and access, the locations are served up to the patient one-by-one automatically.
• Let Greenlight collect it. You can send only Patient and Order data to Greenlight, then launch the Greenlight application. Greenlight's app will walk the patient through entering their medical record locations, as well as granting consent and access, and return the Request information to you at the end, after the patient is redirected back to your app.

DETAILS

Create Patient
This is where you pass the patient's name, date of birth, zip code, sex assigned at birth, mobile phone (for Greenlight to text the invitation), email (a backup invitation method and required identifier), etc. See the API Reference for details, including which values are required.

Once you pass patient data, the Greenlight API passes back a patientId, which you will need for all API requests for this patient in the future.

Create Order and Record Request(s)
This is where you pass your organization's identifier for this medical records order.
Greenlight calls this identifier the External Order ID (it might be a claim number, an account number, a patient medical record number, etc.). This External Order ID helps your team and Greenlight Support discuss Orders and Requests. You can attach more than one identifier as part of this External Order Id (for example, some businesses have several insurance claims that will use this same medical records request for approval - you can send all those claim numbers, comma separated, for this one Order and use any of them to refer to it later in API calls or when talking to GL Support). There is a 64 character limit for each identifier (externalOrderId) you send.

At the same time you create the Order, you can pass the details for each of the places where the medical records reside (practice/facility name, address, phone, doctor name, etc.). Greenlight calls each of these a Record Request. The API accepts up to ten Record Requests in the initial Create Order API request. For example, if you needed records from the patient's hospital, family practice, and a specialist - that would be three Records Requests in the one Order, and you can send the Order and all three Record Requests with one API request.

To create an Order you will need the patientId provided in the Create Patient step above.
The API will respond with an orderId (Greenlight's internal id for this Order) and requestIds which you should store for future API requests.

Add Requests to Existing Order
Often the medical records, upon review by your organization, reveal other records which need to be requested. This endpoint allows you to add one or more additional Record Requests onto the same Order.

To create Requests you will need the patientId and the orderId provided in the steps above.
The API will respond with requestIds which you should store for future reference.

At this point in the lifecycle, Greenlight invites the patient to use Greenlight's User application to consent to Greenlight's Terms of Service and provide the access we need for each medical record request.

Then Greenlight retrieves the records from the EHRs, using our retrieval engines. If there is a roadblock preventing Greenlight from retrieving the records, an error message will be produced. Your organization can check on the progress, and know when we have documents for you, by performing an API call to Find Changes.

Special Note about "Customer Name"

The default setting at Greenlight is to show the Customer name in all Greenlight patient facing communication and application screens. The patient sees this as "who is requesting records." We allow customers to over-ride this name, Order by Order, if needed.

For example, if your name is known to your customer, but the patient would be more likely to recognize (and trust) the name of a healthcare facility where they are enrolled in a trial or study, you can set the Order with the study site's name, and Greenlight will display that name, instead of your Customer name, when communicating with patients.

NOTE: This is a customer configuration, which Customer Success must enable, before it can be used.

See the API Reference sections for Create an Order, for more details.