Using this Guide

This guide is structured as follows:

• Introductory sections ("GETTING STARTED") which help you:
  • decide which integration path you will take (Greenlight has two, Lite and Full),
  • understand terminology, some of which is unique to Greenlight
  • use Greenlight's different environments for testing and production
  • avoid some of the most common mistakes ("Important Considerations")
  • understand Greenlight's approach to timestamping, security, error messaging, and future changes to this API
• More detailed descriptions of the API resources ("WORKFLOWS")
  • Divided into two lists, tailored to the two Greenlight integration paths (Lite or Full).

The Record Request Lifecycle

Before you begin coding and testing the API, it helps to understand story arc of the medical records request - what Greenlight calls the Request Lifecycle.

When your organization orders medical records today, you could divide the work into four basic stages:

1. You prove your organization is authorized to get the records
2. You provide the details about the patient and the medical facility where the records are
3. You check on the status of your request (are the records available to you yet?)
4. You pick up or download the records and pass them to the right people in your organization

These are the four basic stages in the Greenlight API process, as well:

1. Verification and manage Tokens
2. Request Records - provide patient, order, and medical record request data (where the records are)
3. Find Changes (what's different since the last time you checked - any new records in?)
4. Fetch Documents and Data

(For the technical details, see the API Reference section.)

Verification and Token Management

When your organization contracts with Greenlight for medical records access, Greenlight generates for you a customerID, a unique clientSecret, and a unique x-api-key. The combination of these allows you to identify yourself and get a token. One or more of these identifiers are used in every Greenlight API request, to confirm you are who you say you are. You should store and handle these fields with the utmost security - they are your organization's unique and confidential passkeys to Greenlight. For more information about these secure identifiers, see the Security section.

When you successfully verify your identity (with the customerId, x-api-key, and clientSecret), the Greenlight API responds with a token. This is a long, random string that has a lifespan. You must use that token, along with other identifiers listed above, to make every API request in the rest of the description below.

Your system will need to recognize when the token has expired and request a new one as needed. If you attempt to make an API request with an expired token, the API will respond with a "not authorized" error.

Once you have the token, you can use it for the Greenlight workflows, Request Records, Find Changes, and Fetch Documents/Data.

Request Records

This is the workflow for passing Patient, Order, and Records Request data to Greenlight so we can retrieve the records. We require six data elements to create a Patient, an order ID from your system, and information about where the records are (practice/facility name, address, ZIP, etc.).

Find Changes

Greenlight has provided a simple method to discover changes in the status of your Record Requests. The Changes service takes a starting time you indicate, and sends back information about two things that have happened at Greenlight since: new documents and data ready for pickup, and Record Requests that have had a status change.

Fetch Documents and Data

When the Changes service provides information about newly retrieved documents (CCDs or FHIR R4 data), that information includes the data elements needed to make an API request for the individual documents and data.

For technical details on these steps, such as required data elements for each API request, possible responses and their meanings, example request code in different languages, etc., see the API Reference section.

Environments

Greenlight provides customers with two environments.
The Test environment (also called "sandbox") is used for initial development and testing.
The Production environment is where real patient data resides and "live" activity takes place with your customers (patients and their records you request).
These environments are fully separated and your access to them is independent.

Two Integration Types

The Greenlight platform provides two levels of integration, lite and full. Each provides different amounts of control and requires different amounts of development work. See the next section to understand the choices. Our Customer Success team can also give advice on combined or "hybrid" workflows, which leverage aspects of both.

The Workflow section of this guide is organized in two paths, one for the lite integration, the other for the full integration. See the Two Integration Types section for more information.