Guides
Start typing to search…

Find Changes - Lite

Find updates to requests and available documents/data.

There are two different ways to get Changes from Greenlight

  1. Changes Since
    1. This is a global (all Record Requests) way to find out what's new since the last time you checked. You don't need to check, patient-by-patient or request-by-request - you just call this endpoint to see anything that's been updated since your last check. This check is limited to the last 30 days, but the correct way to use this is to check once a day, once an hour, once every 15 minutes - whatever makes sense for your implementation.
  2. Changes by Request
    1. This is a single Record Request call for up to a year at a time, to get all data and documents Greenlight retrieved. Some customers use Changes Since (above) to track Status changes and to pick up first retrievals of data... Then they ignore subsequent data retrievals for those Record Requests until months later, when a trial is finished, or treatment is completed, or a disability period is over. Only then do they want all the data/documents which Greenlight has continued to pick up.

Changes Since

The Find changes since timestamp endpoint will return any Record Request which has a new patient document or FHIR data associated with it OR has been cancelled.

  • If Greenlight has retrieved a new document (CCD) or FHIR data since the time you indicated, the response will contain the data you need to download that document/data. See Fetch Document.

  • If Greenlight has changed the status of a Record Request since the time you indicated, the response will contain the requestStatus, externalOrderId orderId, and requestId, so you can take the appropriate action. Greenlight will cancel the Record Request if the patient refused to give access, if the patient couldn't give us their correct portal credentials, if there is no portal, or if the portal is not one supported by Greenlight.

    • For the Lite Integration, Greenlight will handle next steps for all Request Status values, except CANCELLED. CANCELLED is your signal that the retrieval process can't be fulfilled, or the patient has not provided access.

The Changes service responds with the time it "ended" (nextStartingTimestamp) - this is the time you should store and use the next time you call (startingTimestamp), to get all changes since then. This allows your system to detect every new document or data that is available or any Record Request cancellations.

The result of the Find changes since timestamp endpoint will look something like:

{
  "nextStartingTimestamp": "2022-11-22T15:47:41Z",
  "results": [
    {
      "externalOrderId": "someOrderId",
      "lastUpdated": "2022-11-15T05:41:36.304Z",
      "orderId": "8700b3b7-5252-4f14-88be-23b452bae88f",
      "patientId": "d9c8cd04-a792-4bc9-af18-49f4610b7338",
      "requestId": "a541209e-e177-41cd-abd3-bad3ffc8391e",
      "requestStatus": "CANCELLED",
      "terminationReason": "CANCELLED_DUPLICATE"
    },
    {
      "coverageStartDate": "2022-01-01",
      "coverageEndDate": "",
      "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": "DATA_RETR",
      "terminationReason": ""
    },
		{
      "coverageStartDate": "2022-01-01",
      "coverageEndDate": "",
      "documentFetchDate": "2022-11-17T05:14:53.906Z",
      "documentId": "6375c34d3889960001ea73b9",
      "documentType": "ENCOUNTER_CCD",
      "externalOrderId": "15,855",
      "lastUpdated": "2022-11-16T06:04:46.316Z",
      "orderId": "beadfb56-0117-42c7-bb3d-161ba70de325",
      "patientId": "0dd90ec4-908f-485b-bb04-f1be9c7a596f",
      "requestId": "e5204137-e348-400c-b7db-18c33397e1fd",
      "requestStatus": "DATA_RETR",
      "terminationReason": ""
     }    
  ]
}

(NOTE: For more official examples of API response json, see the API Reference.)

nextStartingTimestamp is the value you should use as startingTimestamp when making your next Changes call.

results will be an array of items which have changed since the startingTimestamp. If there are no changes, the results element will be an empty array.

Requests which have had a Status change will appear with the requestStatus populated.

(For the Lite Integration, only the CANCELLED Status is a call to action for your system; the other status values show Greenlight progress, but Greenlight will be taking the next steps.)

Status values which Greenlight reports include:

  • CRED_SKIPPED - the end user passed over this Request without entering credentials or granting access
  • CRED_FAILED - the credentials the end user provided to Greenlight get a login error from the portal
  • FHIR_TOKEN_EXPIRED - the token the end user granted to Greenlight has expired
  • DATA_RETR - this is primarily used to indicate there are new or updated FHIR R4 resources available to fetch. For customers using CCDs, ignore these messages and work directly with the messages containing the document Ids.
  • DATA_UNAV_2FA - This portal account is set up with multi-factor authentication. Greenlight can send the patient instructions in this case. Patients can often disable the 2FA setting long enough for Greenlight to pick up records, then turn it back on. Greenlight may also have other retrieval paths (such as FHIR endpoints).
  • DATA_UNAV_USER_INTERACTION_NEEDED - The end user needs to perform some task in the portal before Greenlight can retrieve the records. Greenlight can send the patient a notification in this case, and patients generally can resolve the issue, so Greenlight's next retry will get records.
  • DOB_CHECK_FAILED - Greenlight detected a discrepancy between the date of birth in the records and the date of birth on file for this patient. The end user needs to log back in and re-enable the connection in their FHIR portal before Greenlight can make another attempt to retrieve records. When this error is triggered, Greenlight does not store records retrieved and discards the FHIR authorization, preventing further retrieval attempts until the patient returns to the app.
  • CANCELLED - Greenlight or the end user have cancelled this Request, stopping all activity.
  • CLOSED - Greenlight has closed this Request. Data fetching is still allowed, for data already retrieved.

Requests which have new documents will contain documentId, documentType, documentFetchDate, coverageStartDate, and coverageEndDate. Use these values to call Fetch a document, to retrieve the contents of the CCD. See the Fetch Document workflow and the Fetch a document section of the API Reference.

Coverage Dates - Document "Coverage" dates refer to the time period represented in the CCD. Typically an Encounter CCD contains a short span of time (often a single day) representing data for one medical event. Summary CCDs refer to broader ranges, often from the date the patient's records were started at the facility until the latest medical event.

Termination Reason - This value is only populated on CANCELLED Status Requests. Requests can be cancelled by the patient, by the customer, and by the Greenlight platform (automation). The three automated cancellation reasons are:

  • CANCELLED_DUPLICATE - Indicates that the Request would have retrieved the same records as another active Request on the same Order, so the platform cancelled it. (Two Requests with different Coverage Dates set on them will never be seen as duplicates, even if they would have retrieved the same, or a subset of the same records.)
  • CANCELLED_CONFIDENCE_RED - Indicates the Request was for a healthcare location that Greenlight cannot access.
  • CANCELLED_NO_ACTIVITY - Greenlight allows customers to set a time limit for Requests, after which the platform will cancel the Request, so there is an announcement in the Changes API. This allows customers to move on to other retrieval methods if the patient fails to engage in the process.

Handling Duplicates

There is a small chance that responses to subsequent Changes calls will contain duplicate entries. To check for duplicates, the requestId and lastUpdated should always be unique.

Here are two scenarios we've seen that can create duplicates: 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 Changes response because it is exactly on the "startingTimestamp" mark. We err on the side of alerting you twice rather than missing an event.


Changes by Request

The Changes by Request endpoint will return all data and document items that are new or updated since your start time. You can set start time (required) and end time, and cover a period up to a year long.

The response is in the same format as Changes Since (above), but leaves out Status changes. For R4, where a resource might have been mentioned in Changes several times over the timeframe, only the most recent entry is returned. When you fetch an R4 resource you always get the current state of the data, so you only need one Changes reference to prompt you to fetch it.

Updated 3 months ago