Important Considerations

Over the years Greenlight has had the opportunity to observe API implementation best practices in action.

The following tips are important for getting the best from the Greenlight API, and for making maintenance, testing, and adoption of new Greenlight features as simple as possible.

Token management

The security of the data entrusted to us is our primary concern. For that reason the Greenlight API uses a bearer token for all calls related to patient data. When you are issued a token it has a lifespan. Greenlight may decide at any point, for security reasons, to change that lifespan. Due to the critical nature of security management, that change might be made suddenly, with little or no notice.

What this means for you is that you must manage the token lifespan and token expiration in a way that doesn't assume a particular lifespan for the token. Tokens are always issued with data about their expiration. The best implementation would always detect dynamically if your token has expired, and request a new one as often as it's needed.

Timestamps

Be sure to review the Timestamps section on how to handle all timestamps in the request and response with Greenlight.

The flexibility of JSON - use the names!

API responses are structured as JSON. This means all data returned to your system is presented as "name": "value" pairs.

All of your logic to reference those values should use the "name": "value" pair, NOT position.

For example, here is a portion of a response you might receive when requesting Changes in the Greenlight API. The response sends you information about new documents (medical records).

Here is a JSON snip:

{
      "documentFetchDate": "2022-11-17T05:14:53.906Z",
      "documentId": "6375c34d3889960001ea73b8",
      "documentType": "CCD",
      "externalOrderId": "15,855",
      "lastUpdated": "2022-11-16T06:04:45.869Z",
      "orderId": "beadfb56-0117-42c7-bb3d-161ba70de325",
      "patientId": "0dd90ec4-908f-485b-bb04-f1be9c7a596f",
      "requestId": "e5204137-e348-400c-b7db-18c33397e1fd",
      "requestStatus": "ACTIVE"
}

Your next API call might be to GET the document, using the documentId, which is in the second position. Your code should not get the documentId by position (second spot in the order of values above) but by name (documentId).

Greenlight will continue to enhance the API in the future, by adding additional features and data. As an example, what if Greenlight added some kind of flag called "documentActive."

The response might now look like:

{
      "documentActive": "ACTIVE",
      "documentFetchDate": "2022-11-17T05:14:53.906Z",
      "documentId": "6375c34d3889960001ea73b8",
      "documentType": "CCD",
      "externalOrderId": "15,855",
      "lastUpdated": "2022-11-16T06:04:45.869Z",
      "orderId": "beadfb56-0117-42c7-bb3d-161ba70de325",
      "patientId": "0dd90ec4-908f-485b-bb04-f1be9c7a596f",
      "requestId": "e5204137-e348-400c-b7db-18c33397e1fd",
      "requestStatus": "ACTIVE"
}

If your code had been built based on position, the second position is not documentId anymore - it's documentFetchDate now.

Use the names - it's one of the main benefits of JSON.

Tracking the next "from" time, for Finding Changes

The Find Changes API returns a "nextStartingTimestamp," which represents the time of the latest change reported. This is the "from" time you should submit on your next Find Changes API request, so you pick up everything new and minimize duplicates.

It's important to store this value for your next Find Changes API request.

For more details, see Find Changes and the more technical Find changes since timestamp section of the API Reference

Duplicate checking

There are several reasons why you might receive a document or change event from Greenlight again. Here are two we've seen:
a. Your system may have sent an older "from" time for Changes, in which case your system might retrieve those documents and events a second time.
b. There is a tiny chance that Greenlight would send a duplicate in a later Find Changes response because it is exactly on the "from" mark. We err on the side of alerting you twice rather than missing an event.

For more details, see the section for Find Changes - look for the subsection about handling duplicates.

Request Ids, for easier document and FHIR data matching

The API returns orderId, requestId, practiceName, and practiceZipCode in responses after creating record Requests. The practice name and ZIP values are the same that you sent to Greenlight when you created or added Requests, and can be used to match to the medical record request in your system. A more precise method, however, would be to store and use the Greenlight requestId.

For more details about record Requests, see Request Records
See the Add Requests section of the API Reference for more information about the response.

Error handling

The Greenlight API returns specific, informative error information to help you inform your users what's needed when something fails. The errors follow a uniform pattern. Since there can be dozens of different unique error text messages, and new ones may be added in the future, it is best practice to program your responses based on the HTTP codes and to pass the specific text messages on to a program or user who can respond. This is particularly true for errors about data format and required data values (all indicated in the API Reference, for each API request).

It's also important to deliberately test failing API requests, prior to going "Live" in Production. The best way to become familiar with errors and error responses is to test for them.

Transaction logging

When calling for Greenlight support, as you develop or troubleshoot the integration, it is vital to be able to share the http requestid of any transaction that you need to reference. This enables Greenlight to trace the transaction and provide insights into resolution.