Request Details by Order

Once the patient is finished in the Greenlight app, granting consent and providing access, you use this API request to get any changes to the Record Requests.

Any changes the patient made to the record location name, address, etc.
What portal or access point Greenlight matched to that location
The retrieval confidence indicator for that portal or access point (green, yellow, red)

The Request data can be retrieved with just the Customer Id, the Patient Id and the Order Id. The response contains all Requests for that Order. See the technical reference for more details.

Portal or Access Point

Greenlight's platform automatically matches most Requests to a known data access point. Where there is no match, the platform creates a temporary match which is reviewed (by software and administrators) for potential addition to the Greenlight directory.

Portals and access points have a name, which may be different from the location name (the Request name). For example, a specialty clinic may have a name that commemorates a founding physician (Jones Memorial Clinic). The portal, however, may be named for the large health system that owns that clinic, and which has a single portal for ALL their practices (River Valley Health System). This information is not critical for the integration, but it may be useful for your medical record data handling downstream.

Portals and access points also have a "Type" value. The type usually indicates the EHR brand of the portal ("Epic" for example), and whether the FHIR endpoint was used ("Epic FHIR"). This is also not critical for the integration, but it may be useful for your medical record data handling downstream.

Request Status

Request Status is used to trigger work flow steps and patient engagement events. Some status values (typically the status values that create Changes entries) are signals, needing action. Others are only for use in the Greenlight platform, and require no action by the patient or by you and your application.

The list below shows all Request Status values which might appear in the Request Data by Order response, and what action is needed, if any. Statuses are listed below in approximate chronological order, following the life cycle of a Request. Not all Requests go through all statuses.

CREATED - No action required. Initial status of all Requests.
AUTO_MATCHED - No action required. An internal Greenlight platform status, part of the search and match process.
MATCHED – Action depends on Confidence score. MATCHED indicates the patient or Greenlight has selected a records location for the Request. If the Confidence score is “Red,” it indicates that Greenlight does not have access to these records – action may be required. You will need to get these medical records by another method. If the Confidence score is “Green” or “Yellow,” the patient did not finish granting access, and you may need to call them back to your app to.
PENDING - No action required. An internal Greenlight platform status, part of the invitation process for the Lite Integration.
ACTIVE - No action required. An internal Greenlight platform status, part of the retrieval process.
NO_DATA - No action required. An internal Greenlight platform status, part of the retrieval process used to trigger retries that some EHR brands require. Also used in the Greenlight deduplication process. It is normal for Requests to hold this status between refreshes, if there is no new data since the last retrieval.
DATA_UNAV - No action required. An internal Greenlight platform status, part of the retrieval process used to trigger retries that some EHR brands require. May also indicate a transient problem on the EHR side; Greenlight retry and refresh processes typically overcome this type of short-term issue.
DATA_UNAV_2FA - Action required. This status is for Portal DRE retrievals, only (it does not affect FHIR retrievals). Greenlight is unable to retrieve records from the patient portal because the portal has multi-factor authorization enabled. Instruct the patient to log into their portal and disable the multi-factor auth long enough for Greenlight to retrieve the data. Note: Some EHRs do not allow 2FA to be turned off. In these cases, Greenlight will not be able to retrieve records from this portal.
DATA_UNAV_NEEDS_USER_INTERACTION - Action required. This status is for Portal DRE retrievals, only (it does not affect FHIR retrievals). Greenlight is unable to retrieve records from the patient portal because the portal pops a task the patient must complete first. Instruct the patient to login to their portal to finish the task, then the next Greenlight retry or refresh will get records.
CRED_FAILED - Action required. This status is for Portal DRE retrievals, only (it does not affect FHIR retrievals). The credentials the patient provided fail to access the portal. Instruct the patient to return to the Greenlight app, which will instruct the patient to provide new credentials. A help screen in the app offers advice on resetting portal password, if needed.
FHIR_TOKEN_EXPIRED - Action required. This status is for FHIR retrievals, only (it does not affect Portal DRE retrievals). The token the patient enabled for Greenlight access has expired and can no longer be renewed by Greenlight without patient engagement. Instruct the patient to return to the Greenlight app to renew access.
DOB_CHECK_FAILED - Greenlight compares the DOB provided on the Patient object (see the Request Records sections) to the DOB in the FHIR data we are about to retrieve. If there is a discrepancy, we do not retrieve or store the data, and we apply this error to the Request. The most common cause is the patient selecting the wrong family member when providing access to the FHIR endpoint for the EHR. Instruct the patient to return to the Greenlight app and try again.
CRED_SKIPPED - Action required. The patient skipped this Request while in the Greenlight app. Instruct the patient to return to the Greenlight app to complete the process.
DATA_RETR – Action required. The most recent Greenlight retrieval attempt found new data, which is ready for fetching. The Changes API will have details about available data.
DATA_SENT – No action required. This is an internal Greenlight status indicating a recent data fetch.
CLOSED – No action required. The Request has been closed by Greenlight, as completed. Data can still be fetched.
CANCELLED - Action may be required. A Request can be cancelled several ways. Greenlight may cancel a Request because it will not retrieve data. Greenlight may also cancel a Request to replace it with a new Request, to try a different access path. The patient may have deliberately deleted the connection in the Greenlight app, stopping access.

Retrieval Confidence

Greenlight catalogs known US medical locations and portals and monitors their status. Greenlight returns a Retrieval Confidence Indicator value for each Request, which summarizes the likelihood that records can be retrieved.

Green - A portal or endpoint that Greenlight supports and which reliably returns records
Yellow - A new location, for which Greenlight needs to discover a portal or access point. This color might also indicate a portal that Greenlight knows to be less reliable for retrieval.
Red - This location either has no portal at all (no electronic patient access for medical records) or this location uses a niche specialty patient portal for which Greenlight hasn't built a retrieval engine yet.